angel_shelf 1.2.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 12

shelf

Pub build status

Shelf interop with Angel. This package lets you run package:shelf handlers via a custom adapter. It also includes a plug-in that configures Angel to natively run shelf response handlers.

Use the code in this repo to embed existing shelf apps into your Angel 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.

Usage

embedShelf

This is a compliant shelf adapter that acts as an Angel request handler. You can use it as a middleware, or attach it to individual routes.

import 'dart:io';
import 'package:angel_framework/angel_framework.dart';
import 'package:angel_shelf/angel_shelf.dart';
import 'package:shelf/shelf.dart' as shelf;
import 'api/api.dart';

main() async {
  final app = new Angel();
  
  // Angel routes on top
  await app.configure(new ApiController());
  
  // Re-route all other traffic to an
  // existing application.
  app.after.add(embedShelf(
    new shelf.Pipeline()
      .addMiddleware(shelf.logRequests())
      .addHandler(_echoRequest)
  ));
  
  // Only on a specific route
  app.get('/shelf', handler);
  
  await app.startServer(InternetAddress.LOOPBACK_IP_V4, 3000);
}

Communicating with Angel with embedShelf

You can communicate with Angel:

handleRequest(shelf.Request request) {
  // Access original Angel request...
  var req = request.context['angel_shelf.request'] as RequestContext;
  
  // ... And then interact with it.
  req.inject('from_shelf', new Foo());
  
  // `req.properties` are also available.
  var props = request.context['angel_shelf.properties'] as Map;
  
}

supportShelf

This plug-in takes advantage of Angel's middleware system and dependency injection to patch a server to run shelf request handlers as though they were Angel request handlers. Hooray for integration!

You'll want to run this before adding any other response finalizers that depend on the response content being effectively final, i.e. GZIP compression.

NOTE: Do not inject a shelf.Request into your request under the name req. If you do, Angel will automatically inject a RequestContext instead.

configureServer(Angel app) async {
  // Return a shelf Response
  app.get('/shelf', (shelf.Request request) => new shelf.Response.ok('Yay!'));
  
  // Return an arbitrary value.
  //
  // This will be serialized by Angel as per usual.
  app.get('/json', (shelf.Request request) => {'foo': 'bar'});
  
  // You can still throw Angel exceptions.
  //
  // Don't be fooled: just because this is a shelf handler, doesn't mean
  // it's not an Angel response handler too. ;)
  app.get('/error', (shelf.Request request) {
    throw new AngelHttpException.forbidden();
  });
  
  // Make it all happen!
  await app.configure(supportShelf());
}

Communicating with Angel with supportShelf

The following keys will be present in the shelf request's context:

  • angel_shelf.request - Original RequestContext
  • angel_shelf.response - Original ResponseContext
  • angel_shelf.properties - Original RequestContext's properties

If the original RequestContext contains a Map named shelf_context in its properties, then it will be merged into the shelf request's context.

If the handler returns a shelf.Response, then it will be present in ResponseContext.properties as shelf_response.

1.2.0

  • Upgraded for >=1.1.0 compatibility.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  angel_shelf: ^1.2.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:angel_shelf/angel_shelf.dart';
  
Version Uploaded Documentation Archive
1.2.0 Jan 9, 2018 Go to the documentation of angel_shelf 1.2.0 Download angel_shelf 1.2.0 archive
1.1.1 Jun 20, 2017 Go to the documentation of angel_shelf 1.1.1 Download angel_shelf 1.1.1 archive
1.1.0 Jun 12, 2017 Go to the documentation of angel_shelf 1.1.0 Download angel_shelf 1.1.0 archive
1.0.0 Jan 13, 2017 Go to the documentation of angel_shelf 1.0.0 Download angel_shelf 1.0.0 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
0
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
60
Overall:
Weighted score of the above. [more]
12
Learn more about scoring.

We analyzed this package on Oct 22, 2018, and provided a score, details, and suggestions below. Analysis was completed with status tool failures using:

  • Dart: 2.0.0
  • pana: 0.12.4

Platforms

Detected platforms: unsure

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

Analysis issues and suggestions

Fix dependencies in pubspec.yaml.

Running pub upgrade failed with the following output:

ERR: The current Dart SDK version is 2.0.0.
 
 Because angel_shelf depends on shelf >=0.0.0-dev+1 <=0.7.3+2 which requires SDK version >=1.0.0 <2.0.0-∞, version solving failed.

Health suggestions

Format lib/angel_shelf.dart.

Run dartfmt to format lib/angel_shelf.dart.

Maintenance issues and suggestions

Fix platform conflicts. (-20 points)

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

The description is too short. (-20 points)

Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

Maintain an example.

None of the files in your example/ directory matches a known example patterns. Common file name patterns include: main.dart, example.dart or you could also use angel_shelf.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.19.0