99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# Protevus Shelf
|
|
|
|
|
|
[](https://dart.dev/null-safety)
|
|
[](https://discord.gg/3X6bxTUdCM)
|
|
[](https://github.com/dart-backend/protevus/tree/master/packages/shelf/LICENSE)
|
|
|
|
**Replacement of `package:angel_shelf` with breaking changes to support NNBD.**
|
|
|
|
Shelf interop with Protevus. This package lets you run `package:shelf` handlers via a custom adapter. Use the code in this repo to embed existing Protevus/shelf apps into other Protevus/shelf applications. This way, you can migrate legacy applications without having to rewrite your business logic. This will make it easy to layer your API over a production application, rather than having to port code.
|
|
|
|
- [Protevus Shelf](#protevus-shelf)
|
|
- [Usage](#usage)
|
|
- [embedShelf](#embedshelf)
|
|
- [Communicating with Protevus with embedShelf](#communicating-with-protevus-with-embedshelf)
|
|
- [AngelShelf](#angelshelf)
|
|
|
|
## Usage
|
|
|
|
### embedShelf
|
|
|
|
This is a compliant `shelf` adapter that acts as an Protevus request handler. You can use it as a middleware,
|
|
or attach it to individual routes.
|
|
|
|
```dart
|
|
import 'dart:io';
|
|
import 'package:angel3_framework/angel3_framework.dart';
|
|
import 'package:angel3_shelf/angel3_shelf.dart';
|
|
import 'package:shelf/shelf.dart' as shelf;
|
|
import 'api/api.dart';
|
|
|
|
void main() async {
|
|
var app = Protevus();
|
|
var http = AngelHttp(app);
|
|
|
|
// Protevus routes on top
|
|
await app.mountController<ApiController>();
|
|
|
|
// Re-route all other traffic to an
|
|
// existing application.
|
|
app.fallback(embedShelf(
|
|
shelf.Pipeline()
|
|
.addMiddleware(shelf.logRequests())
|
|
.addHandler(_echoRequest)
|
|
));
|
|
|
|
// Or, only on a specific route:
|
|
app.get('/shelf', wrappedShelfHandler);
|
|
|
|
await http.startServer(InternetAddress.loopbackIPV4, 3000);
|
|
print(http.uri);
|
|
}
|
|
```
|
|
|
|
### Communicating with Protevus with embedShelf
|
|
|
|
You can communicate with Protevus:
|
|
|
|
```dart
|
|
handleRequest(shelf.Request request) {
|
|
// Access original Protevus request...
|
|
var req = request.context['angel_shelf.request'] as RequestContext;
|
|
|
|
// ... And then interact with it.
|
|
req.container.registerNamedSingleton<Foo>('from_shelf', Foo());
|
|
|
|
// `req.container` is also available.
|
|
var container = request.context['angel_shelf.container'] as Container;
|
|
container.make<Truck>().drive();
|
|
}
|
|
```
|
|
|
|
### AngelShelf
|
|
|
|
Protevus brought about the generic `Driver` class, which is implemented by `AngelHttp`, `AngelHttp2`, `AngelGopher`, etc., and provides the core infrastructure for request handling in Protevus. `AngelShelf` is an implementation that wraps shelf requests and responses in their Protevus equivalents. Using it is as simple using as using `AngelHttp`, or any other driver:
|
|
|
|
```dart
|
|
// Create an AngelShelf driver.
|
|
// If we have startup hooks we want to run, we need to call
|
|
// `startServer`. Otherwise, it can be omitted.
|
|
// Of course, if you call `startServer`, know that to run
|
|
// shutdown/cleanup logic, you need to call `close` eventually,
|
|
// too.
|
|
var angelShelf = AngelShelf(app);
|
|
await angelShelf.startServer();
|
|
|
|
await shelf_io.serve(angelShelf.handler, InternetAddress.loopbackIPv4, 8081);
|
|
```
|
|
|
|
You can also use the `AngelShelf` driver as a shelf middleware - just use
|
|
`angelShelf.middleware` instead of `angelShelf.handler`. When used as a middleware,
|
|
if the Protevus response context is still open after all handlers run (i.e. no routes were
|
|
matched), the next shelf handler will be called.
|
|
|
|
```dart
|
|
var handler = shelf.Pipeline()
|
|
.addMiddleware(angelShelf.middleware)
|
|
.addHandler(createStaticHandler(...));
|
|
```
|