52 lines
2.1 KiB
Dart
52 lines
2.1 KiB
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.
|
||
|
|
|
||
|
|
import 'dart:async';
|
||
|
|
|
||
|
|
import 'handler.dart';
|
||
|
|
|
||
|
|
/// An [adapter][] with a concrete URL.
|
||
|
|
///
|
||
|
|
/// [adapter]: https://github.com/dart-lang/shelf#adapters
|
||
|
|
///
|
||
|
|
/// The most basic definition 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, the 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<void> close();
|
||
|
|
}
|