=encoding utf8
=head1 NAME
std/web - Request, response, and routing helpers for ZuzuScript web apps.
=head1 SYNOPSIS
from std/web import Request, Response, Routes;
class Hello {
static method greet ( req ) {
return new Response(
status: 200,
headers: { "Content-Type": "text/plain; charset=UTF-8" },
body: [ "Hello ", req.param("name"), "\n" ],
);
}
}
let routes := new Routes();
routes.get("/hello/:name").to(
controller: Hello,
action: "greet",
);
function __request__ ( env ) {
return routes.dispatch( new Request( env: env ) );
}
=head1 IMPLEMENTATION SUPPORT
This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
Electron. It is partially supported by zuzu-js in the browser (filesystem
backed template rendering fails).
=head1 DESCRIPTION
This pure ZuzuScript module provides a small web framework layer over the
raw C<__request__(env)> protocol used by ZuzuScript web hosts. It
provides request, response, route match, route, and router objects.
=head1 EXPORTS
=head2 C<Request>
C<Request> wraps the web environment C<Dict> passed to
C<__request__(env)>.
=over
=item * C<set_session_handler(handler)>
Parameters: C<handler> is a C<SessionHandler> object or C<null>.
Returns: the handler. Sets the process-local session handler used by
C<session()>.
=item * C<get_session_handler()>
Parameters: none. Returns: C<SessionHandler> or C<null>. Returns the
process-local session handler.
=item * C<set_route_match(captures, route)>
Parameters: C<captures> is a C<Dict> or C<null>; C<route> is a
C<Route>. Returns: C<Request>. Stores the route captures and matched
route on the request. This is normally called by C<Routes.dispatch>.
=item * C<env()>
Parameters: none. Returns: C<Dict>. Returns the original request
environment.
=item * C<captures()>
Parameters: none. Returns: C<Dict>. Returns captures from the matched
route.
=item * C<stash()>
Parameters: none. Returns: C<Dict>. Returns a mutable copy of the
matched route captures for per-request application state.
=item * C<route()>
Parameters: none. Returns: C<Route> or C<null>. Returns the route that
matched the request.
=item * C<address()>
Parameters: none. Returns: C<String> or C<null>. Returns
C<remote_addr> from the environment.
=item * C<remote_host()>
Parameters: none. Returns: C<String> or C<null>. Returns
C<remote_host>, falling back to C<address()>.
=item * C<request_method()>
Parameters: none. Returns: C<String>. Returns the HTTP request method.
This method is not named C<method()> because C<method> is a ZuzuScript
keyword.
=item * C<protocol()>
Parameters: none. Returns: C<String>. Returns the HTTP protocol, such
as C<HTTP/1.1>.
=item * C<request_uri()>
Parameters: none. Returns: C<String>. Returns the original request URI
when available, or reconstructs it from the raw path and query string.
=item * C<path_info()>
Parameters: none. Returns: C<String>. Returns the request path from the
environment.
=item * C<path()>
Parameters: none. Returns: C<String>. Returns the request path,
normalizing an empty path to C</>.
=item * C<raw_path()>
Parameters: none. Returns: C<String>. Returns the undecoded path when
the host provides one, falling back to C<path()>.
=item * C<query_string()>
Parameters: none. Returns: C<String>. Returns the raw query string
without a leading question mark.
=item * C<script_name()>
Parameters: none. Returns: C<String>. Returns the mounting path for the
application, or an empty string.
=item * C<scheme()>
Parameters: none. Returns: C<String>. Returns the URL scheme, usually
C<http> or C<https>.
=item * C<secure()>
Parameters: none. Returns: C<Boolean>. Returns true when the scheme is
C<https>.
=item * C<body()>
Parameters: none. Returns: any value or C<null>. Returns the raw body
value from the environment.
=item * C<input()>
Parameters: none. Returns: any value or C<null>. Alias for C<body()>.
=item * C<content()>
Parameters: none. Returns: any value or C<null>. Alias for C<body()>.
=item * C<raw_body()>
Parameters: none. Returns: any value or C<null>. Alias for C<body()>.
=item * C<body_text()>
Parameters: none. Returns: C<String> or C<null>. Returns the decoded
request body text when the host provides it.
=item * C<user()>
Parameters: none. Returns: C<String> or C<null>. Returns the remote
authenticated user from the environment.
=item * C<session()>
Parameters: none. Returns: C<Session>, any value, or C<null>. Returns
the request session from the configured C<SessionHandler>. If no handler
is configured, it preserves the middleware/host fallback and returns the
C<session> environment value.
=item * C<session_options()>
Parameters: none. Returns: any value or C<null>. Returns session
options supplied by middleware or the host.
=item * C<logger()>
Parameters: none. Returns: any value or C<null>. Returns a logger
object supplied by middleware or the host.
=item * C<headers()>
Parameters: none. Returns: C<PairList>. Returns request headers.
=item * C<header(name)>
Parameters: C<name> is a C<String>. Returns: C<String> or C<null>.
Returns the first request header matching C<name>, using
case-insensitive matching.
=item * C<content_type()>
Parameters: none. Returns: C<String> or C<null>. Returns the
C<Content-Type> request header.
=item * C<content_length()>
Parameters: none. Returns: C<String> or C<null>. Returns the
C<Content-Length> request header.
=item * C<content_encoding()>
Parameters: none. Returns: C<String> or C<null>. Returns the
C<Content-Encoding> request header.
=item * C<referer()>
Parameters: none. Returns: C<String> or C<null>. Returns the
C<Referer> request header.
=item * C<user_agent()>
Parameters: none. Returns: C<String> or C<null>. Returns the
C<User-Agent> request header.
=item * C<cookies()>
Parameters: none. Returns: C<Dict>. Parses and returns cookies from the
C<Cookie> request header.
=item * C<query_parameters()>
Parameters: none. Returns: C<PairList>. Parses and returns query string
parameters. Duplicate names are preserved.
=item * C<body_parameters()>
Parameters: none. Returns: C<PairList>. Parses and returns
C<application/x-www-form-urlencoded> body parameters. Duplicate names
are preserved.
=item * C<parameters()>
Parameters: none. Returns: C<PairList>. Returns query parameters, body
parameters, and route captures in that order.
=item * C<param(name?)>
Parameters: optional C<name> is a C<String>. Returns: C<String>,
C<Array>, or C<null>. With a name, returns the first matching merged
parameter. With no name, returns the available parameter names.
=item * C<uploads()>
Parameters: none. Returns: C<PairList>. Returns uploaded file entries
from the environment, or an empty C<PairList>.
=item * C<upload(name?)>
Parameters: optional C<name> is a C<String>. Returns: an upload value,
C<Array>, or C<null>. With a name, returns the first matching upload.
With no name, returns the available upload names.
=item * C<uri()>
Parameters: none. Returns: C<String>. Builds the full request URI from
the scheme, host, raw path, and query string.
=item * C<base()>
Parameters: none. Returns: C<String>. Builds the application base URI
from the scheme, host, and script name.
=item * C<new_response(...args, named)>
Parameters: optional positional values are C<status>, C<headers>, and
C<body>; optional named values are C<status>, C<headers>, and C<body>.
Returns: C<Response>. Creates a response associated with the request.
=back
=head2 C<Response>
C<Response> builds the three-item response array returned by the raw web
protocol.
=over
=item * C<status(value?)>
Parameters: optional C<value> is a C<Number>. Returns: C<Number> when
reading, or C<Response> when setting. Gets or sets the HTTP status code.
=item * C<code(value?)>
Parameters: optional C<value> is a C<Number>. Returns: C<Number> when
reading, or C<Response> when setting. Alias for C<status()>.
=item * C<headers(value?)>
Parameters: optional C<value> is a C<PairList> or C<Dict>. Returns:
C<PairList> when reading, or C<Response> when setting. Gets or replaces
the response headers.
=item * C<header(name, value?)>
Parameters: C<name> is a C<String>; optional C<value> is a C<String>.
Returns: C<String> or C<null> when reading, or C<Response> when setting.
Gets or replaces a response header using case-insensitive matching.
=item * C<body(value?)>
Parameters: optional C<value> is any response body value. Returns: the
current body when reading, or C<Response> when setting. Gets or sets the
response body.
=item * C<content(value?)>
Parameters: optional C<value> is any response body value. Returns: the
current body when reading, or C<Response> when setting. Alias for
C<body()>.
=item * C<render(template, data := {})>
Parameters: C<template> is a C<ZTemplate>, C<ZZTemplate>, another object
with a C<process(data)> method, or a C<std/io> C<Path>; C<data> is the
template data model. Returns: C<Response>. Renders the template with
C<data> and sets the response body to the rendered string. Path
templates are compiled as C<ZZTemplate> objects and cached with
C<std/cache/lru>.
=item * C<content_type(value?)>
Parameters: optional C<value> is a C<String>. Returns: C<String> or
C<null> when reading, or C<Response> when setting. Gets or sets the
C<Content-Type> response header.
=item * C<render_json(data)>
Parameters: C<data> is any JSON-encodable value. Returns:
C<Response>. Encodes C<data> as compact JSON, sets the response body to
the JSON text, and sets C<Content-Type> to
C<application/json; charset=UTF-8>.
=item * C<session(value?)>
Parameters: optional C<value> is a C<Session> object. Returns:
C<Session> or C<Response>. Gets or sets the session object that should
contribute a response cookie.
=item * C<content_length(value?)>
Parameters: optional C<value> is a C<String> or C<Number>. Returns:
C<String> or C<null> when reading, or C<Response> when setting. Gets or
sets the C<Content-Length> response header.
=item * C<content_encoding(value?)>
Parameters: optional C<value> is a C<String>. Returns: C<String> or
C<null> when reading, or C<Response> when setting. Gets or sets the
C<Content-Encoding> response header.
=item * C<location(value?)>
Parameters: optional C<value> is a C<String>. Returns: C<String> or
C<null> when reading, or C<Response> when setting. Gets or sets the
C<Location> response header.
=item * C<redirect(url, status := 302)>
Parameters: C<url> is a C<String>; optional C<status> is a C<Number>.
Returns: C<Response>. Sets the redirect status code and C<Location>
header.
=item * C<cookies()>
Parameters: none. Returns: C<Dict>. Returns the response cookies that
have been set with C<set_cookie()>.
=item * C<set_cookie(name, value, options := {})>
Parameters: C<name> and C<value> are C<String>; C<options> is a C<Dict>.
Returns: C<Response>. Adds a C<Set-Cookie> header and stores the cookie
value. Supported options are C<Path>, C<Domain>, C<Expires>,
C<Max-Age>, C<HttpOnly>, C<Secure>, and C<SameSite>.
=item * C<finalize()>
Parameters: none. Returns: C<Array>. Finalizes any attached C<Session>,
sets its cookie, and returns the raw C<[ status, headers, body ]>
response array.
=back
=head2 C<SessionHandler>
C<SessionHandler> is the trait enforced by C<Request.session()>.
Implementations return an object that does C<Session>.
=over
=item * C<session_for(request)>
Parameters: C<request> is a C<Request>. Returns: C<Session>. Loads or
creates the request session.
=back
=head2 C<Session>
C<Session> is the trait enforced by C<Response.finalize()>.
=over
=item * C<finalize()>
Parameters: none. Returns: C<Session>. Writes pending data, is
idempotent, and returns the session object.
=item * C<is_finalized()>
Parameters: none. Returns: C<Boolean>.
=item * C<id()>
Parameters: none. Returns: C<String>.
=item * C<age()>
Parameters: none. Returns: C<Number>.
=item * C<cookie_name()>
Parameters: none. Returns: C<String>.
=item * C<cookie_value()>
Parameters: none. Returns: C<String>.
=item * C<cookie_options()>
Parameters: none. Returns: C<Dict>. Returns options suitable for
C<Response.set_cookie()>.
=back
=head2 C<RouteMatch>
C<RouteMatch> is the match object used internally by the router. It has
no public methods. Its fields are C<route>, C<captures>, and
C<position>.
=head2 C<Route>
C<Route> represents a route node. Applications usually create route
nodes through a C<Routes> object.
=over
=item * C<root()>
Parameters: none. Returns: C<Routes> or C<Route>. Returns the root
router for this route tree.
=item * C<route_types()>
Parameters: none. Returns: C<Dict>. Returns the named placeholder types
available from the root router.
=item * C<parent()>
Parameters: none. Returns: C<Route> or C<null>. Returns the parent route
node.
=item * C<children()>
Parameters: none. Returns: C<Array>. Returns child route nodes.
=item * C<pattern()>
Parameters: none. Returns: C<String>. Returns the route pattern for
this node.
=item * C<methods(...args)>
Parameters: zero or more C<String> methods, or one C<Array> of method
strings. Returns: C<Array> when reading, or C<Route> when setting. Gets
or replaces the allowed HTTP methods.
=item * C<name(value?)>
Parameters: optional C<value> is a C<String>. Returns: C<String> when
reading, or C<Route> when setting. Gets or sets the route name.
=item * C<has_custom_name()>
Parameters: none. Returns: C<Boolean>. Returns true when C<name()> has
explicitly set the route name.
=item * C<inline(value?)>
Parameters: optional C<value> is a truthy or falsey value. Returns:
C<Boolean> when reading, or C<Route> when setting. Gets or sets whether
the route is an inline bridge route created by C<under()>.
=item * C<add_child(route)>
Parameters: C<route> is a C<Route>. Returns: C<Route>. Attaches the
route as a child and returns the child route.
=item * C<remove()>
Parameters: none. Returns: C<Route>. Detaches the route from its parent.
=item * C<any(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting any HTTP
method.
=item * C<get(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting C<GET>.
=item * C<post(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting C<POST>.
=item * C<put(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting C<PUT>.
=item * C<patch(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting C<PATCH>.
=item * C<delete(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting
C<DELETE>.
=item * C<options(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting
C<OPTIONS>.
=item * C<head(...args, named)>
Parameters: optional pattern, route name, action, requirements, and
named values. Returns: C<Route>. Adds a child route accepting C<HEAD>.
=item * C<under(...args, named)>
Parameters: optional pattern, action, requirements, and named values.
Returns: C<Route>. Adds an inline child route that can guard or group
nested routes.
=item * C<parse(pattern, named)>
Parameters: C<pattern> is a C<String>; optional named values are route
requirements. Returns: C<Route>. Replaces the route pattern and applies
requirements.
=item * C<requires(value?, named)>
Parameters: optional C<value> is a C<Dict>, C<PairList>, or flat
C<Array>; optional named values are also requirements. Returns:
C<Route>. Adds capture, method, host, or header requirements.
=item * C<to(value?, named)>
Parameters: optional C<value> is a controller, C<Function>, C<Dict>, or
C<PairList>; named values may include C<controller> and C<action>.
Returns: C<Route>. Sets the route target and stores other named values
as defaults. String controller targets have the form
C<module/path#ClassName> and are lazy loaded with
C<std/internals.load_module>.
=item * C<is_endpoint()>
Parameters: none. Returns: C<Boolean>. Returns true when the route has
an action or controller target.
=item * C<render(values := {})>
Parameters: C<values> is a C<Dict> or C<PairList>. Returns: C<String>.
Builds a path by filling route placeholders with defaults and supplied
values.
=item * C<find(wanted)>
Parameters: C<wanted> is a C<String>. Returns: C<Route> or C<null>.
Finds a route by name within this route tree.
=item * C<lookup(wanted)>
Parameters: C<wanted> is a C<String>. Returns: C<Route> or C<null>.
Alias for C<find()>.
=item * C<match(req)>
Parameters: C<req> is a C<Request>. Returns: C<RouteMatch> or C<null>.
Finds the first route matching the request path, requirements, and HTTP
method.
=item * C<dispatch(request_or_env)>
Parameters: C<request_or_env> is a C<Request> or environment C<Dict>.
Returns: C<Array>. Dispatches to the matching action and returns a raw
C<[ status, headers, body ]> response array. It returns C<404> when no
route matches and C<405> when only the method is wrong.
=back
=head2 C<Routes>
C<Routes> is the root route node. It inherits the C<Route> methods and
adds router-wide placeholder type and condition registries.
=over
=item * C<add_type(name, constraint)>
Parameters: C<name> is a C<String>; C<constraint> is a C<Regexp>,
C<Array>, C<Function>, or comparable value. Returns: C<Routes>. Adds a
named placeholder type for route patterns such as C<< <id:num> >>.
=item * C<route_types()>
Parameters: none. Returns: C<Dict>. Returns the root router's named
placeholder type registry. C<num> is registered by default.
=item * C<add_condition(name, condition)>
Parameters: C<name> is a C<String>; C<condition> is any value. Returns:
C<Routes>. Stores a named condition for application use.
=back
=head1 COPYRIGHT AND LICENCE
B<< std/web >> is copyright Toby Inkster.
It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.
=cut
from std/internals import load_module;
from std/cache/lru import Cache;
from std/data/json import JSON;
from std/net/url import escape, unescape;
from std/string import index, join, replace, split, substr;
from std/template/z import ZTemplate;
from std/template/zz import ZZTemplate;
let _response_template_cache := new Cache( capacity: 64 );
let _response_json := new JSON();
let _session_handler := null;
function _s ( value ) {
return value ≡ null ? "" : "" _ value;
}
function _trim_slashes ( String path ) {
let out := path;
while ( length out > 1 and substr( out, length out - 1, 1 ) ≡ "/" ) {
out := substr( out, 0, length out - 1 );
}
return out;
}
function _path_segments ( pathish ) {
let path := _s(pathish);
path := "/" if path ≡ "";
path := _trim_slashes(path);
path := substr( path, 1 ) if substr( path, 0, 1 ) ≡ "/";
return [] if path ≡ "";
return split( path, "/" );
}
function _decode_form_part ( part ) {
return unescape( replace( _s(part), /\+/, " ", "g" ) );
}
function _parse_params ( query ) {
let params := new PairList();
let text := _s(query);
return params if text ≡ "";
for ( let piece in split( text, "&" ) ) {
next if piece ≡ "";
let eqpos := index( piece, "=" );
let key;
let value;
if ( eqpos < 0 ) {
key := _decode_form_part(piece);
value := "";
}
else {
key := _decode_form_part( substr( piece, 0, eqpos ) );
value := _decode_form_part( substr( piece, eqpos + 1 ) );
}
params.add( key, value );
}
return params;
}
function _parse_cookie_header ( text ) {
let cookies := {};
for ( let part in split( _s(text), ";" ) ) {
let piece := part;
while ( length piece > 0 and substr( piece, 0, 1 ) ≡ " " ) {
piece := substr( piece, 1 );
}
let eqpos := index( piece, "=" );
next if eqpos <= 0;
cookies.set(
substr( piece, 0, eqpos ),
_decode_form_part( substr( piece, eqpos + 1 ) ),
);
}
return cookies;
}
function _header_name ( name ) {
return lc( _s(name) );
}
function _headers_from ( value ) {
let headers := new PairList();
if ( value ≡ null ) {
return headers;
}
if ( value instanceof PairList ) {
for ( let p in value.enumerate() ) {
headers.add( _s( p.key ), _s( p.value ) );
}
return headers;
}
if ( value instanceof Dict ) {
for ( let p in value.enumerate() ) {
headers.add( _s( p.key ), _s( p.value ) );
}
return headers;
}
die "headers must be a PairList or Dict";
}
function _header_get_all ( PairList headers, name ) {
let wanted := _header_name(name);
let out := [];
for ( let p in headers.enumerate() ) {
if ( _header_name( p.key ) ≡ wanted ) {
out.push( p.value );
}
}
return out;
}
function _header_get ( PairList headers, name, fallback := null ) {
let all := _header_get_all( headers, name );
return all.length() ? all[0] : fallback;
}
function _header_remove ( PairList headers, name ) {
let wanted := _header_name(name);
headers.remove( fn p -> _header_name( p.key ) ≡ wanted );
}
function _looks_like_response_array ( value ) {
return (
value instanceof Array and
value.length() = 3 and
value[0] instanceof Number
);
}
function _dict_copy ( value ) {
let out := {};
if ( value instanceof Dict or value instanceof PairList ) {
for ( let p in value.enumerate() ) {
out.set( p.key, p.value );
}
}
return out;
}
function _response_template ( template ) {
from std/io try import Path;
function _response_template_cache_key ( path_obj ) {
let canonical := path_obj.realpath();
if ( canonical ≡ null ) {
canonical := path_obj.absolute();
}
if ( canonical ≡ null ) {
return path_obj.to_String;
}
if ( canonical instanceof Path ) {
return canonical.to_String;
}
return "" _ canonical;
}
if ( Path ≡ null ) {
return template;
}
if ( template instanceof Path ) {
let path_obj := template;
return _response_template_cache.get(
_response_template_cache_key(path_obj),
fn key -> new ZZTemplate( file: path_obj ),
);
}
return template;
}
trait SessionHandler {
method session_for ( request ) {
die "SessionHandler.session_for is not implemented";
}
}
trait Session {
method finalize () {
die "Session.finalize is not implemented";
}
method is_finalized () {
die "Session.is_finalized is not implemented";
}
method id () {
die "Session.id is not implemented";
}
method age () {
die "Session.age is not implemented";
}
method cookie_name () {
die "Session.cookie_name is not implemented";
}
method cookie_value () {
die "Session.cookie_value is not implemented";
}
method cookie_options () {
die "Session.cookie_options is not implemented";
}
}
class Response {
let Number status := 200;
let headers := null;
let body := [];
let session := null;
let Dict cookies := {};
let Number _status := 200;
let PairList _headers := new PairList();
let _body := [];
let _session := null;
let Dict _cookies := {};
let Boolean _session_cookie_set := false;
method __build__ () {
_status := status;
_headers := _headers_from(headers);
_body := body;
_session := session;
_cookies := cookies;
}
method status ( value? ) {
if ( value ≢ null ) {
_status := value;
}
return _status;
}
method code ( value? ) {
return self.status(value);
}
method headers ( value? ) {
if ( value ≢ null ) {
_headers := _headers_from(value);
}
return _headers;
}
method header ( name, value? ) {
if ( value ≢ null ) {
_header_remove( _headers, name );
_headers.add( _s(name), _s(value) );
return self;
}
return _header_get( _headers, name );
}
method body ( value? ) {
if ( value ≢ null ) {
_body := value;
}
return _body;
}
method content ( value? ) {
return self.body(value);
}
method render ( template, data := {} ) {
let renderer := _response_template(template);
_body := renderer.process(data);
return self;
}
method render_json ( data ) {
_body := _response_json.encode(data);
self.content_type("application/json; charset=UTF-8");
return self;
}
method session ( value? ) {
if ( value ≢ null ) {
_session := value;
_session_cookie_set := false;
return self;
}
return _session;
}
method content_type ( value? ) {
return value ≡ null
? self.header("Content-Type")
: self.header( "Content-Type", value );
}
method content_length ( value? ) {
return value ≡ null
? self.header("Content-Length")
: self.header( "Content-Length", value );
}
method content_encoding ( value? ) {
return value ≡ null
? self.header("Content-Encoding")
: self.header( "Content-Encoding", value );
}
method location ( value? ) {
return value ≡ null
? self.header("Location")
: self.header( "Location", value );
}
method redirect ( url, status := 302 ) {
_status := status;
self.location(url);
return self;
}
method cookies () {
return _cookies;
}
method set_cookie ( name, value, options := {} ) {
let cookie := escape(name) _ "=" _ escape(value);
if ( options instanceof Dict ) {
for ( let key in [ "Path", "Domain", "Expires", "Max-Age" ] ) {
if ( options.exists(key) ) {
cookie _= "; " _ key _ "=" _ options.get(key);
}
}
cookie _= "; HttpOnly" if options.get( "HttpOnly", false );
cookie _= "; Secure" if options.get( "Secure", false );
cookie _= "; SameSite=" _ options.get("SameSite")
if options.exists("SameSite");
}
_cookies.set( name, value );
_headers.add( "Set-Cookie", cookie );
return self;
}
method _finalize_session () {
return self if _session ≡ null or _session_cookie_set;
_session := _session.finalize() unless _session.is_finalized();
self.set_cookie(
_session.cookie_name(),
_session.cookie_value(),
_session.cookie_options(),
);
_session_cookie_set := true;
return self;
}
method finalize () {
self._finalize_session();
return [ _status, _headers, _body ];
}
}
class Request {
let Dict env := {};
let Dict _captures := {};
let Dict _stash := {};
let _route := null;
let _query_parameters := null;
let _body_parameters := null;
let _parameters := null;
let _cookies := null;
let _session := null;
let Boolean _session_loaded := false;
static method set_session_handler ( handler ) {
_session_handler := handler;
return handler;
}
static method get_session_handler () {
return _session_handler;
}
method set_route_match ( captures, route ) {
_captures := captures ≡ null ? {} : captures;
_stash := _dict_copy(_captures);
_route := route;
return self;
}
method env () {
return env;
}
method captures () {
return _captures;
}
method stash () {
return _stash;
}
method route () {
return _route;
}
method address () {
return env.get( "remote_addr", null );
}
method remote_host () {
return env.get( "remote_host", self.address() );
}
method request_method () {
return env.get( "method", "" );
}
method protocol () {
return env.get( "protocol", env.get( "server_protocol", "HTTP/1.1" ) );
}
method request_uri () {
let raw := env.get( "request_uri", null );
return raw if raw ≢ null;
let qs := self.query_string();
return self.raw_path() _ ( qs ≡ "" ? "" : "?" _ qs );
}
method path_info () {
return env.get( "path", "" );
}
method path () {
let p := self.path_info();
return p ≡ "" ? "/" : p;
}
method raw_path () {
return env.get( "raw_path", self.path() );
}
method query_string () {
return env.get( "query_string", "" );
}
method script_name () {
return env.get( "script_name", "" );
}
method scheme () {
return env.get( "scheme", "http" );
}
method secure () {
return self.scheme() ≡ "https";
}
method body () {
return env.get( "body", null );
}
method input () {
return self.body();
}
method content () {
return self.body();
}
method raw_body () {
return self.body();
}
method body_text () {
return env.get( "body_text", null );
}
method user () {
return env.get( "remote_user", null );
}
method session () {
let handler := Request.get_session_handler();
return env.get( "session", null ) if handler ≡ null;
if ( not _session_loaded ) {
_session := handler.session_for(self);
_session_loaded := true;
}
return _session;
}
method session_options () {
return env.get( "session_options", null );
}
method logger () {
return env.get( "logger", null );
}
method headers () {
return env.get( "headers", new PairList() );
}
method header ( name ) {
return _header_get( self.headers(), name );
}
method content_type () {
return self.header("Content-Type");
}
method content_length () {
return self.header("Content-Length");
}
method content_encoding () {
return self.header("Content-Encoding");
}
method referer () {
return self.header("Referer");
}
method user_agent () {
return self.header("User-Agent");
}
method cookies () {
if ( _cookies ≡ null ) {
_cookies := _parse_cookie_header( self.header( "Cookie" ) );
}
return _cookies;
}
method query_parameters () {
if ( _query_parameters ≡ null ) {
_query_parameters := _parse_params( self.query_string() );
}
return _query_parameters;
}
method body_parameters () {
if ( _body_parameters ≡ null ) {
let ct := _s( self.content_type() );
_body_parameters := new PairList();
if (
self.body_text() ≢ null and
index( lc(ct), "application/x-www-form-urlencoded" ) = 0
) {
_body_parameters := _parse_params( self.body_text() );
}
}
return _body_parameters;
}
method parameters () {
if ( _parameters ≡ null ) {
_parameters := new PairList();
for ( let p in self.query_parameters().enumerate() ) {
_parameters.add( p.key, p.value );
}
for ( let p in self.body_parameters().enumerate() ) {
_parameters.add( p.key, p.value );
}
for ( let p in _captures.enumerate() ) {
_parameters.add( p.key, p.value );
}
}
return _parameters;
}
method param ( name? ) {
if ( name ≡ null ) {
return self.parameters().keys();
}
return self.parameters().get(name);
}
method uploads () {
return env.get( "uploads", new PairList() );
}
method upload ( name? ) {
if ( name ≡ null ) {
return self.uploads().keys();
}
return self.uploads().get(name);
}
method uri () {
let qs := self.query_string();
return (
self.scheme() _ "://" _
env.get( "host", env.get( "server_name", "" ) ) _
self.raw_path() _
( qs ≡ "" ? "" : "?" _ qs )
);
}
method base () {
return (
self.scheme() _ "://" _
env.get( "host", env.get( "server_name", "" ) ) _
self.script_name()
);
}
method new_response ( ... Array args, PairList named ) {
let status := args.length() > 0 ? args[0] : named.get( "status", 200 );
let headers := args.length() > 1 ? args[1] : named.get( "headers", null );
let body := args.length() > 2 ? args[2] : named.get( "body", null );
return new Response(
status: status,
headers: headers,
body: body,
session: named.get( "session", null ),
);
}
}
function _method_allowed ( Array methods, String method_name ) {
return true if methods.empty();
let m := uc(method_name);
m := "GET" if m ≡ "HEAD";
for ( let allowed in methods ) {
return true if uc(allowed) ≡ m;
}
return false;
}
function _regexp_match ( value, expected ) {
if ( typeof expected ≡ "Regexp" ) {
return _s(value) ~ expected;
}
if ( expected instanceof Array ) {
return expected.any( fn x -> _s(x) ≡ _s(value) );
}
if ( expected instanceof Function ) {
return expected(value);
}
return _s(value) ≡ _s(expected);
}
function _default_route_name ( pattern ) {
let parts := _path_segments(pattern);
return "root" if parts.empty();
return join( "_", parts.map( fn p -> replace( p, /^[:#*<]+|>$/g, "" ) ) );
}
function _parse_route_segment ( seg ) {
if ( substr( seg, 0, 1 ) ≡ ":" ) {
return {
kind: "placeholder",
name: substr( seg, 1 ),
style: "standard",
type: null,
};
}
if ( substr( seg, 0, 1 ) ≡ "#" ) {
return {
kind: "placeholder",
name: substr( seg, 1 ),
style: "relaxed",
type: null,
};
}
if ( substr( seg, 0, 1 ) ≡ "*" ) {
return {
kind: "placeholder",
name: substr( seg, 1 ),
style: "wildcard",
type: null,
};
}
if (
substr( seg, 0, 1 ) ≡ "<" and
substr( seg, length seg - 1, 1 ) ≡ ">"
) {
let inner := substr( seg, 1, length seg - 2 );
let style := "standard";
if ( substr( inner, 0, 1 ) ≡ ":" ) {
inner := substr( inner, 1 );
}
else if ( substr( inner, 0, 1 ) ≡ "#" ) {
style := "relaxed";
inner := substr( inner, 1 );
}
else if ( substr( inner, 0, 1 ) ≡ "*" ) {
style := "wildcard";
inner := substr( inner, 1 );
}
let colon := index( inner, ":" );
let ptype := null;
if ( colon >= 0 ) {
ptype := substr( inner, colon + 1 );
inner := substr( inner, 0, colon );
}
return {
kind: "placeholder",
name: inner,
style: style,
type: ptype,
};
}
return { kind: "literal", text: seg };
}
function _parse_route_pattern ( pattern ) {
let out := [];
for ( let seg in _path_segments(pattern) ) {
let part := _parse_route_segment(seg);
out.push(part);
}
return out;
}
function _placeholder_ok ( part, value, types ) {
return false if value ≡ "";
if ( part{style} ≡ "standard" and index( value, "." ) >= 0 ) {
return false;
}
if ( part{type} ≢ null ) {
return false unless types.exists( part{type} );
return false unless _regexp_match( value, types.get( part{type} ) );
}
return true;
}
function _match_parts ( parts, pi, segs, si, captures, types ) {
if ( pi >= parts.length() ) {
return { position: si, captures: captures };
}
return null if si > segs.length();
let part := parts[pi];
if ( part{kind} ≡ "literal" ) {
return null if si >= segs.length();
return null if unescape( segs[si] ) ≢ part{text};
return _match_parts( parts, pi + 1, segs, si + 1, captures, types );
}
if ( part{style} ≡ "wildcard" ) {
let end := segs.length();
while ( end >= si ) {
let copy := _dict_copy(captures);
let captured := [];
let i := si;
while ( i < end ) {
captured.push( unescape( segs[i] ) );
i++;
}
copy.set( part{name}, join( "/", captured ) );
let matched := _match_parts( parts, pi + 1, segs, end, copy, types );
return matched if matched ≢ null;
end--;
}
return null;
}
return null if si >= segs.length();
let value := unescape( segs[si] );
return null if not _placeholder_ok( part, value, types );
let copy := _dict_copy(captures);
copy.set( part{name}, value );
return _match_parts( parts, pi + 1, segs, si + 1, copy, types );
}
function _split_controller_string ( spec ) {
let hash := index( spec, "#" );
die "controller string must be module#ClassName" if hash <= 0;
let module := substr( spec, 0, hash );
let name := substr( spec, hash + 1 );
die "invalid controller module name"
unless module ~ /^[A-Za-z_][A-Za-z0-9_]*(\/[A-Za-z_][A-Za-z0-9_]*)*$/;
die "invalid controller class name"
unless name ~ /^[A-Za-z_][A-Za-z0-9_]*$/;
return { module: module, class: name, controller: spec, action: null };
}
function _response_value ( value ) {
return value.finalize() if value instanceof Response;
return value if _looks_like_response_array(value);
return new Response( status: 204, body: [] ).finalize() if value ≡ null;
return new Response( status: 200, body: value ).finalize();
}
class RouteMatch {
let route := null;
let captures := {};
let Number position := 0;
}
class Route {
let _root := null;
let _parent := null;
let Array _children := [];
let Array _methods := [];
let String _pattern := "/";
let Array _parts := [];
let Dict _defaults := {};
let Dict _requires := {};
let _target_action := null;
let _target_controller := null;
let _target_module := null;
let _target_class := null;
let _loaded_controller := null;
let String _name := "";
let Boolean _custom_name := false;
let Boolean _inline := false;
method __build__ () {
_root := self if _root ≡ null;
_parent := null if _parent ≡ self;
_parts := _parse_route_pattern(_pattern);
_name := _default_route_name(_pattern) if _name ≡ "";
}
method root () {
return _root;
}
method route_types () {
return {};
}
method parent () {
return _parent;
}
method children () {
return _children;
}
method pattern () {
return _pattern;
}
method methods ( ... Array args ) {
if ( args.length() > 0 ) {
_methods := [];
let raw := args[0];
if ( raw instanceof Array ) {
for ( let m in raw ) {
_methods.push( uc(_s(m)) );
}
}
else {
for ( let m in args ) {
_methods.push( uc(_s(m)) );
}
}
return self;
}
return _methods;
}
method name ( value? ) {
if ( value ≢ null ) {
_name := _s(value);
_custom_name := true;
return self;
}
return _name;
}
method has_custom_name () {
return _custom_name;
}
method inline ( value? ) {
if ( value ≢ null ) {
_inline := value ? true : false;
return self;
}
return _inline;
}
method add_child ( Route route ) {
route._detach();
route._set_parent(self);
_children.push(route);
return route;
}
method remove () {
self._detach();
return self;
}
method _detach () {
if ( _parent ≢ null ) {
_parent.children().remove( fn r -> r ≡ self );
_parent := null;
}
return self;
}
method _set_parent ( parent ) {
_parent := parent;
_root := parent.root();
return self;
}
method any ( ... Array args, PairList named ) {
return self._add_route( [], args, named, false );
}
method get ( ... Array args, PairList named ) {
return self._add_route( [ "GET" ], args, named, false );
}
method post ( ... Array args, PairList named ) {
return self._add_route( [ "POST" ], args, named, false );
}
method put ( ... Array args, PairList named ) {
return self._add_route( [ "PUT" ], args, named, false );
}
method patch ( ... Array args, PairList named ) {
return self._add_route( [ "PATCH" ], args, named, false );
}
method delete ( ... Array args, PairList named ) {
return self._add_route( [ "DELETE" ], args, named, false );
}
method options ( ... Array args, PairList named ) {
return self._add_route( [ "OPTIONS" ], args, named, false );
}
method head ( ... Array args, PairList named ) {
return self._add_route( [ "HEAD" ], args, named, false );
}
method under ( ... Array args, PairList named ) {
return self._add_route( [], args, named, true );
}
method _add_route ( methods, args, named, inline ) {
let route := new Route(
_root: self.root(),
_pattern: "/",
_methods: methods,
_inline: inline,
);
let i := 0;
if ( args.length() > 0 and args[0] instanceof Array ) {
route.methods(args[0]);
i := 1;
}
if ( i < args.length() and args[i] instanceof String ) {
route.parse(args[i]);
i++;
}
while ( i < args.length() ) {
let item := args[i];
if ( item instanceof Dict or item instanceof PairList ) {
route.to(item);
}
else if ( item instanceof Array ) {
route._apply_require_array(item);
}
else if ( item instanceof Function ) {
route.to( action: item );
}
else if ( item instanceof String ) {
route.name(item);
}
i++;
}
route.requires(named) unless named.empty();
self.add_child(route);
return route;
}
method parse ( pattern, ... PairList named ) {
_pattern := _s(pattern);
_parts := _parse_route_pattern(_pattern);
_name := _default_route_name(_pattern) unless _custom_name;
self.requires(named) unless named.empty();
return self;
}
method requires ( value? ... PairList named ) {
if ( value ≢ null ) {
if ( value instanceof Array ) {
self._apply_require_array(value);
}
else if ( value instanceof Dict or value instanceof PairList ) {
for ( let p in value.enumerate() ) {
_requires.set( p.key, p.value );
}
}
else {
die "requires expects a Dict, PairList, or Array";
}
}
for ( let p in named.enumerate() ) {
_requires.set( p.key, p.value );
}
return self;
}
method _apply_require_array ( Array pairs ) {
let i := 0;
while ( i + 1 < pairs.length() ) {
_requires.set( pairs[i], pairs[ i + 1 ] );
i += 2;
}
return self;
}
method to ( value? ... PairList named ) {
if ( value ≢ null ) {
if ( value instanceof String and index( value, "#" ) >= 0 ) {
let parsed := _split_controller_string(value);
named.add( "controller", parsed{controller} );
named.add( "action", parsed{action} );
}
else if ( value instanceof Dict or value instanceof PairList ) {
for ( let p in value.enumerate() ) {
named.add( p.key, p.value );
}
}
else if ( value instanceof Function ) {
named.add( "action", value );
}
else {
named.add( "controller", value );
}
}
for ( let p in named.enumerate() ) {
if ( p.key ≡ "action" ) {
_target_action := p.value;
}
else if ( p.key ≡ "controller" ) {
self._set_controller(p.value);
}
else {
_defaults.set( p.key, p.value );
}
}
return self;
}
method _set_controller ( value ) {
if ( value instanceof String and index( value, "#" ) >= 0 ) {
let parsed := _split_controller_string(value);
_target_module := parsed{module};
_target_class := parsed{class};
_target_controller := null;
_loaded_controller := null;
}
else {
_target_controller := value;
_target_module := null;
_target_class := null;
_loaded_controller := null;
}
return self;
}
method _controller () {
return _target_controller if _target_controller ≢ null;
return _loaded_controller if _loaded_controller ≢ null;
return null if _target_module ≡ null;
_loaded_controller := load_module( _target_module, _target_class );
return _loaded_controller;
}
method is_endpoint () {
return _target_action ≢ null or _target_controller ≢ null
or _target_module ≢ null;
}
method render ( values := {} ) {
let data := _dict_copy(_defaults);
for ( let p in values.enumerate() ) {
data.set( p.key, p.value );
}
let parts := [];
for ( let part in _parts ) {
if ( part{kind} ≡ "literal" ) {
parts.push( part{text} );
}
else if ( data.exists( part{name} ) ) {
parts.push( escape( data.get( part{name} ) ) );
}
}
return "/" _ join( "/", parts );
}
method find ( String wanted ) {
return self if _name ≡ wanted;
for ( let child in _children ) {
let found := child.find(wanted);
return found if found ≢ null;
}
return null;
}
method lookup ( String wanted ) {
return self.find(wanted);
}
method match ( Request req ) {
let segs := _path_segments( req.path() );
return self._dispatch_match( req, segs, 0, {} );
}
method dispatch ( request_or_env ) {
let req := request_or_env instanceof Request
? request_or_env
: new Request( env: request_or_env );
let matched := self.match(req);
if ( matched ≢ null ) {
req.set_route_match( matched{captures}, matched{route} );
return _response_value( matched{route}._run(req) );
}
let allowed := self._allowed_methods_for(req);
if ( allowed.length() > 0 ) {
return new Response(
status: 405,
headers: { Allow: join( ", ", allowed ) },
body: [ "Method Not Allowed\n" ],
).finalize();
}
return new Response(
status: 404,
headers: { "Content-Type": "text/plain; charset=UTF-8" },
body: [ "Not Found\n" ],
).finalize();
}
method _run ( Request req ) {
if ( _target_action instanceof Function ) {
return _target_action(req);
}
let controller := self._controller();
if ( controller ≡ null ) {
die "Route has no controller or action";
}
if ( not( _target_action instanceof String ) ) {
die "Route controller target requires a string action";
}
return controller.(_target_action)(req);
}
method _dispatch_match ( req, segs, pos, stash ) {
for ( let child in _children ) {
let local := _dict_copy(stash);
let child_match := child._match_self( req, segs, pos, local, false );
next if child_match ≡ null;
if ( child.inline() and child.is_endpoint() ) {
req.set_route_match( child_match{captures}, child );
next if not child._run(req);
}
let nested := child._dispatch_match(
req,
segs,
child_match{position},
child_match{captures},
);
return nested if nested ≢ null;
if (
child.is_endpoint() and
child_match{position} = segs.length() and
_method_allowed( child.methods(), req.request_method() )
) {
child_match{route} := child;
return child_match;
}
}
return null;
}
method _match_self ( req, segs, pos, captures, ignore_method ) {
let part_match := _match_parts(
_parts,
0,
segs,
pos,
captures,
self.root().route_types(),
);
return null if part_match ≡ null;
return null if not self._requirements_match( req, part_match{captures} );
return null if (
not ignore_method and
self.is_endpoint() and
not _method_allowed( _methods, req.request_method() )
);
for ( let p in _defaults.enumerate() ) {
part_match{captures}.set( p.key, p.value )
unless part_match{captures}.exists( p.key );
}
return new RouteMatch(
route: self,
captures: part_match{captures},
position: part_match{position},
);
}
method _requirements_match ( req, captures ) {
for ( let p in _requires.enumerate() ) {
let value := captures.get( p.key, null );
if ( value ≡ null ) {
if ( p.key ≡ "method" ) {
value := req.request_method();
}
else if ( p.key ≡ "host" ) {
value := req.env().get( "host", "" );
}
else {
value := req.header(p.key);
}
}
return false if not _regexp_match( value, p.value );
}
return true;
}
method _allowed_methods_for ( req ) {
let segs := _path_segments( req.path() );
let methods := [];
self._collect_allowed_methods( req, segs, 0, {}, methods );
return methods;
}
method _collect_allowed_methods ( req, segs, pos, stash, methods ) {
for ( let child in _children ) {
let local := _dict_copy(stash);
let child_match := child._match_self( req, segs, pos, local, true );
next if child_match ≡ null;
child._collect_allowed_methods(
req,
segs,
child_match{position},
child_match{captures},
methods,
);
if ( child.is_endpoint() and child_match{position} = segs.length() ) {
for ( let m in child.methods() ) {
methods.push(m) unless m ∈ methods;
}
}
}
return methods;
}
}
class Routes extends Route {
let Dict _types := {};
let Dict _conditions := {};
method __build__ () {
super();
_types.set( "num", /^[0-9]+$/ );
}
method add_type ( name, constraint ) {
_types.set( name, constraint );
return self;
}
method route_types () {
return _types;
}
method add_condition ( name, condition ) {
_conditions.set( name, condition );
return self;
}
}