shelf 0.5.3

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 47

Web Server Middleware for Dart

Introduction

Shelf makes it easy to create and compose web servers and parts of web servers. How?

  • Expose a small set of simple types.
  • Map server logic into a simple function: a single argument for the request, the response is the return value.
  • Trivially mix and match synchronous and asynchronous processing.
  • Flexibliity to return a simple string or a byte stream with the same model.

Example

See example/example_server.dart

import 'package:shelf/shelf.dart' as shelf;
import 'package:shelf/shelf_io.dart' as io;

void main() {
  var handler = const shelf.Pipeline().addMiddleware(shelf.logRequests())
      .addHandler(_echoRequest);

  io.serve(handler, 'localhost', 8080).then((server) {
    print('Serving at http://${server.address.host}:${server.port}');
  });
}

shelf.Response _echoRequest(shelf.Request request) {
  return new shelf.Response.ok('Request for "${request.url}"');
}

Handlers and Middleware

A handler is any function that handles a shelf.Request and returns a shelf.Response. It can either handle the request itself--for example, a static file server that looks up the requested URI on the filesystem--or it can do some processing and forward it to another handler--for example, a logger that prints information about requests and responses to the command line.

The latter kind of handler is called "middleware", since it sits in the middle of the server stack. Middleware can be thought of as a function that takes a handler and wraps it in another handler to provide additional functionality. A Shelf application is usually composed of many layers of middleware with one or more handlers at the very center; the shelf.Pipeline class makes this sort of application easy to construct.

Some middleware can also take multiple handlers and call one or more of them for each request. For example, a routing middleware might choose which handler to call based on the request's URI or HTTP method, while a cascading middleware might call each one in sequence until one returns a successful response.

Adapters

An adapter is any code that creates shelf.Request objects, passes them to a handler, and deals with the resulting shelf.Response. For the most part, adapters forward requests from and responses to an underlying HTTP server; shelf_io.serve is this sort of adapter. An adapter might also synthesize HTTP requests within the browser using window.location and window.history, or it might pipe requests directly from an HTTP client to a Shelf handler.

When implementing an adapter, some rules must be followed. The adapter must not pass the url or scriptName parameters to new shelf.Request; it should only pass requestedUri. If it passes the context parameter, all keys must begin with the adapter's package name followed by a period. If multiple headers with the same name are received, the adapter must collapse them into a single header separated by commas as per RFC 2616 section 4.2.

An adapter must handle all errors from the handler, including the handler returning a null response. It should print each error to the console if possible, then act as though the handler returned a 500 response. The adapter may include body data for the 500 response, but this body data must not include information about the error that occurred. This ensures that unexpected errors don't result in exposing internal information in production by default; if the user wants to return detailed error descriptions, they should explicitly include middleware to do so.

An adapter should include information about itself in the Server header of the response by default. If the handler returns a response with the Server header set, that must take precedence over the adapter's default header.

An adapter should ensure that asynchronous errors thrown by the handler don't cause the application to crash, even if they aren't reported by the future chain. Specifically, these errors shouldn't be passed to the root zone's error handler; however, if the adapter is run within another error zone, it should allow these errors to be passed to that zone. The following function can be used to capture only errors that would otherwise be top-leveled:

/// Run [callback] and capture any errors that would otherwise be top-leveled.
///
/// If [this] is called in a non-root error zone, it will just run [callback]
/// and return the result. Otherwise, it will capture any errors using
/// [runZoned] and pass them to [onError].
catchTopLevelErrors(callback(), void onError(error, StackTrace stackTrace)) {
  if (Zone.current.inSameErrorZone(Zone.ROOT)) {
    return runZoned(callback, onError: onError);
  } else {
    return callback();
  }
}

Inspiration

0.5.3

  • Add new named parameters to Request.change: scriptName and url.

0.5.2

  • Add a Cascade helper that runs handlers in sequence until one returns a response that's neither a 404 nor a 405.

  • Add a Request.change method that copies a request with new header values.

  • Add a Request.hijack method that allows handlers to gain access to the underlying HTTP socket.

0.5.1+1

  • Capture all asynchronous errors thrown by handlers if they would otherwise be top-leveled.

  • Add more detail to the README about handlers, middleware, and the rules for implementing an adapter.

0.5.1

  • Add a context map to Request and Response for passing data among handlers and middleware.

0.5.0+1

  • Allow scheduled_test development dependency up to v0.12.0

0.5.0

  • Renamed Stack to Pipeline.

0.4.0

  • Access to headers for Request and Response is now case-insensitive.

  • The constructor for Request has been simplified.

  • Request now exposes url which replaces pathInfo, queryString, and pathSegments.

0.3.0+9

  • Removed old testing infrastructure.

  • Updated documentation address.

0.3.0+8

  • Added a dependency on the http_parser package.

0.3.0+7

  • Removed unused dependency on the mime package.

0.3.0+6

  • Added a dependency on the string_scanner package.

0.3.0+5

  • Updated pubspec details for move to Dart SDK.

0.3.0 2014-03-25

  • Response
    • NEW! int get contentLength
    • NEW! DateTime get expires
    • NEW! DateTime get lastModified
  • Request
    • BREAKING contentLength is now read from headers. The constructor argument has been removed.
    • NEW! supports an optional Stream<List<int>> body constructor argument.
    • NEW! Stream<List<int>> read() and Future<String> readAsString([Encoding encoding])
    • NEW! DateTime get ifModifiedSince
    • NEW! String get mimeType
    • NEW! Encoding get encoding

0.2.0 2014-03-06

  • BREAKING Removed Shelf prefix from all classes.
  • BREAKING Response has drastically different constructors.
  • NEW! Response now accepts a body of either String or Stream<List<int>>.
  • NEW! Response now exposes encoding and mimeType.

0.1.0 2014-03-02

  • First reviewed release

Use this package as a library

1. Depend on it

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


dependencies:
  shelf: ^0.5.3

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:shelf/shelf.dart';
  
Version Uploaded Documentation Archive
0.7.3+3 Jul 16, 2018 Go to the documentation of shelf 0.7.3+3 Download shelf 0.7.3+3 archive
0.7.3+2 Jul 10, 2018 Go to the documentation of shelf 0.7.3+2 Download shelf 0.7.3+2 archive
0.7.3+1 May 22, 2018 Go to the documentation of shelf 0.7.3+1 Download shelf 0.7.3+1 archive
0.7.3 May 2, 2018 Go to the documentation of shelf 0.7.3 Download shelf 0.7.3 archive
0.7.2 Jan 4, 2018 Go to the documentation of shelf 0.7.2 Download shelf 0.7.2 archive
0.7.1 Oct 26, 2017 Go to the documentation of shelf 0.7.1 Download shelf 0.7.1 archive
0.7.0 Aug 29, 2017 Go to the documentation of shelf 0.7.0 Download shelf 0.7.0 archive
0.6.8 Jun 23, 2017 Go to the documentation of shelf 0.6.8 Download shelf 0.6.8 archive
0.6.7+2 Dec 6, 2016 Go to the documentation of shelf 0.6.7+2 Download shelf 0.6.7+2 archive
0.6.7+1 Oct 26, 2016 Go to the documentation of shelf 0.6.7+1 Download shelf 0.6.7+1 archive

All 57 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
95
Health:
Code health derived from static analysis. [more]
--
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
--
Overall:
Weighted score of the above. [more]
47
Learn more about scoring.

This package version is not analyzed, because it is more than two years old. Check the latest stable version for its analysis.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Maintenance issues and suggestions

Running dartdoc failed. (-10 points)

Make sure dartdoc runs without any issues.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.4.0 <2.0.0