core library

Used to implement a program that listens for HTTP requests and produces HTTP responses.

Overview

A Web server is represented by a Server object that has been configured with an ordered list of one or more ServerPipeline objects. Pipelines have a list of request handlers, which process the HTTP requests to generate the HTTP responses.

When a request handler is registered with a pipeline, it is associated with a rule. A rule has a HTTP method (e.g. GET or POST) and a pattern for matching against the path of the request URI (e.g. "~/api/foo/:uuid").

When a HTTP request is received, the rules in the server's pipelines are searched for a match. When a match is found, the rule's request handler is invoked.

Request handlers

Request handlers are functions (or static methods) which must match the RequestHandler function signature.

Requests

Request handlers are passed a Request object representing the HTTP request.

The RequestParams class represents parameters from the HTTP request. It is used to represent the URI query parameters, path parameters (corresponding to segments defined by the pattern) and post parameters. Post parameters are only present if the HTTP request has the content-type of "application/x-www-form-urlencoded"—which is the HTTP request produced by submitting a HTML form with the POST method.

If the request belongs to a session, the request includes a Session object.

Responses

Request handlers must return a Future to a Response which is used to generate the HTTP response.

There are four concrete Request classes:

Generating HTML

HTML response is usually produced by writing HTML into a ResponseBuffered.

The HEsc class contains static methods to escape string values for use in HTML formatted responses (e.g. converting < to &lt;).

Static files

The StaticFiles class can be used to create a request handler that produces a response from files and directories.

Testing

Simulated HTTP requests for testing

Instead of invoking run on the server, the Server.simulate method can be used to test the server.

Create a simulated HTTP request using Request.simulatedGet, Request.simulatedPost or Request.simulated and then pass it to the server's simulate method. The response can then be tested for the expected HTTP response.

This type of testing can be used to supplement testing with a Web browser. It has the advantage of running faster than automating the actions of a Web browser, but it also has the disadvantge that it cannot execute any client-side JavaScript.

Logging

The Logger package is used for logging.

Some of the available loggers are named:

  • woomera.server - logs general server behaviour
  • woomera.handles - logs rules created via Handles annotations
  • woomera.request - logs HTTP requests
  • woomera.request.header - details about the headers in the HTTP requests
  • woomera.request.param - details about the parameters extracted from HTTP requests
  • woomera.response - logs responses produced
  • woomera.session - logs information related to state management
  • woomera.static_file - logs static file handler
  • woomera.proxy - logs proxy handler

See the loggers variable for a comprehensive list of all the Loggers used in this library.

Classes

HEsc
Escaping arbitrary values for use in HTML documents.
Pattern
Pattern that is used to match a path.
Proxy
Proxy for handling requests to another server.
Request
Request class.
RequestParams
Represents a collection of parameters.
RequestParamsMutable
A mutable RequestParams.
Response
Abstract base class for a response.
ResponseBuffered
A response where the contents is buffered text.
ResponseNoContent
HTTP response has no response body.
ResponseRedirect
HTTP response that redirects the browser to a URL.
ResponseStream
A response where the contents come from a stream.
Server
A Web server.
ServerPipeline
A pipeline.
ServerRule
Represents a rule for processing HTTP requests.
Session
Session that is maintained between HTTP requests.
SimulatedHttpConnectionInfo
Simulated HTTP connection information.
SimulatedHttpHeaders
Headers in a simulated request or response
SimulatedResponse
Response returned by simulations.
StaticFiles
Handler for returning static files and directory listings.

Enums

ParamsMode
Modes for processing parameter values.
SessionTermination
Reasons why a session was terminated.
SimulatedResponseBodyType
The source format for the body in a simulated response.

Properties

loggers → List<Logger>
List of all the loggers used by this library.
final

Functions

debugHandler(Request req) → Future<Response>
Request handler which shows out the request parameters to the client.

Typedefs

ExceptionHandler = Future<Response> Function(Request request, Object exception, StackTrace stackTrace)
Exception handler for high-level situations.
ExceptionHandlerRaw = Future<void> Function(HttpRequest rawRequest, String requestId, Object exception, StackTrace stackTrace)
Exception handler for low-level situations.
RequestCreator = FutureOr<Request> Function(HttpRequest request, String id, Server server)
Type for a request factory.
RequestHandler = Future<Response> Function(Request req)
HTTP request handler function type.

Exceptions / Errors

DuplicateRule
Attempt to register a duplicate rule in a pipeline.
ExceptionHandlerException
Exception indicating an exception/error occurred in an exception handler.
MalformedPathException
Exception indicating malformed request.
NoResponseFromHandler
Exception to indicate a RequestHandler did not produce a response.
NoResponseProduced
Indicates a handler cannot produce a response.
NotFoundException
Exception indicating a response could not be created.
PathTooLongException
Exception indicating the URL path is too large.
PostTooLongException
Exception indicating the contents of the POST request is too large.
ProxyHandlerException
Exception indicating an exception/error occurred in the proxy handler.
WoomeraException
Base class for all exceptions defined in the Woomera package.