core library

Core library.

This library contains the core features of Woomera, but without the scanning for annotation functions.

Normally, use the full woomera library instead. But if Dart Mirrors cannot be used (e.g. when the program is compiled using dart compile), then this core library can be used by itself.

Listens for HTTP requests and invokes the appropriate request handler, based on rules that are matched against the request. Supports features such as session management and exception handling.

Usage

Define request handler and exception handler functions. Annotations can be placed on them, but will be ignored if the scanner is not used.

import 'package:woomera/core.dart';

Future<Response> homePage(Request req) async {
  final resp = ResponseBuffered(ContentType.html)..write('''
<!DOCTYPE html>
<head>
  <title>Example</title>
</head>
<html>
  <body>
  <p>Hello world!</p>
  </body>
</html>
''');
  return resp;
}

Then create a Server and explicitly register all the handler functions with it. Then run the server.

Future main() async {
  final server = serverFromAnnotations()
    ..bindAddress = InternetAddress.anyIPv6
    ..v6Only = false // false = listen to any IPv4 and any IPv6 address
    ..bindPort = port;

  server.pipelines.first.get('~/', homePage);

  await server.run();
}

Explicitly registering all the handlers can be tedious. Therefore, automatically populating the server from annotations on the handler functions is usually a better approach. The functions for automatically populating a server is defined in the scan library, and can be imported by importing the main woomera library.

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.

Multiple pipelines

Usually, the default ServerPipeline automatically created by the server is sufficient.

For some situations, multiple pipelines can be useful. For example, when it is useful to have a different exception handler for different sets of rules, or to better control the order in which rules are used.

Logging

The Logger package is used for logging. 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

Classes

Handles
Information for creating a rule or initializing exception handlers.
HEsc
HTML escaping methods for escaping values for output in HTML.
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.

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.
HandlerWrapper = RequestHandler Function(Handles rego, Object obj)
Function type for handler wrapper.
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.