blob: e3c216b8c5bed5f31d1c57bd287a45fdd234f71f [file] [log] [blame]
// 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.
import 'dart:async';
import 'handler.dart';
/// An [adapter][] with a concrete URL.
/// [adapter]:
/// 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();