Add a Server interface.

lib/src/server.dart

+// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library shelf.server;
+
+import 'dart:async';
+
+import 'handler.dart';
+
+/// An [adapter][] with a concrete URL.
+///
+/// [adapter]: https://github.com/dart-lang/shelf#adapters
+///
+/// The most basic definiton of "adapter" includes any function that passes
+/// incoming requests to a [Handler] and passes its responses to some external
+/// client. However, in practice, most adapters are also *servers*—that is,
+/// they're serving requests that are made to a certain well-known URL.
+///
+/// This interface represents those servers in a general way. It's useful for
+/// writing code that needs to know its own URL without tightly coupling that
+/// code to a single server implementation.
+///
+/// There are two built-in implementations of this interface. You can create a
+/// server backed by `dart:io` using [IOServer], or you can create a server
+/// that's backed by a normal [Handler] using [ServerHandler].
+///
+/// Implementations of this interface are responsible for ensuring that the
+/// members work as documented.
+abstract class Server {
+  /// The URL of the server.
+  ///
+  /// Requests to this URL or any URL beneath it are handled by the handler
+  /// passed to [mount]. If [mount] hasn't yet been called, the requests wait
+  /// until it is. If [close] has been called, [handler] will not be invoked;
+  /// otherwise, the behavior is implementation-dependent.
+  Uri get url;
+
+  /// Mounts [handler] as the base handler for this server.
+  ///
+  /// All requests to [url] or and URLs beneath it will be sent to [handler]
+  /// until [close] is called.
+  ///
+  /// Throws a [StateError] if there's already a handler mounted.
+  void mount(Handler handler);
+
+  /// Closes the server and returns a Future that completes when all resources
+  /// are released.
+  ///
+  /// Once this is called, no more requests will be passed to this server's
+  /// handler. Otherwise, the cleanup behavior is implementation-dependent.
+  Future close();
+}