AngelShelf docs

README.md

@@ -4,8 +4,8 @@
 
 Shelf interop with Angel. This package lets you run `package:shelf` handlers via a custom adapter. 
 
-Use the code in this repo to embed existing shelf apps into
-your Angel applications. This way, you can migrate legacy applications without
+Use the code in this repo to embed existing Angel/shelf apps into
+other Angel/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,
@@ -14,6 +14,7 @@ rather than having to port code.
 - [Usage](#usage)
   - [embedShelf](#embedshelf)
     - [Communicating with Angel](#communicating-with-angel-with-embedshelf)
+  - [`AngelShelf`](#angelshelf)
 
 # Usage
 
@@ -69,3 +70,36 @@ handleRequest(shelf.Request request) {
   container.make<Truck>().drive();
 }
 ```
+
+### AngelShelf
+Angel 2 brought about the generic `Driver` class, which is implemented
+by `AngelHttp`, `AngelHttp2`, `AngelGopher`, etc., and provides the core
+infrastructure for request handling in Angel.
+
+`AngelShelf` is an implementation that wraps shelf requests and responses in their
+Angel 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 Angel 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(...));
+```

example/angel_in_shelf.dart

@@ -29,8 +29,12 @@ main() async {
   }));
 
   // Next, 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();
 

lib/src/shelf_driver.dart

@@ -25,6 +25,11 @@ class AngelShelf extends Driver<shelf.Request, ShelfResponseContext,
     });
   }
 
+  Future<Stream<shelf.Request>> close() {
+    incomingRequests.close();
+    return super.close();
+  }
+
   Future<Stream<shelf.Request>> Function(dynamic, int) get serverGenerator =>
       (_, __) async => incomingRequests.stream;