section(3, '3.2', swi('/doc/packages/http.html'))

3.2 Library http/http_dispatch -- Dispatch requests in the HTTP server

This module can be placed between http_wrapper.pl and the application code to associate HTTP locations to predicates that serve the pages. In addition, it associates parameters with locations that deal with timeout handling and user authentication. The typical setup is:

server(Port, Options) :-
        http_server(http_dispatch,
                    [ port(Port),
                    | Options
                    ]).

:- http_handler('/index.html', write_index, []).

write_index(Request) :-
        ...

[det]http_handler(+Path, :Closure, +Options)

Register Closure as a handler for HTTP requests. Path is a specification as provided by http_path.pl. If an HTTP request arrives at the server that matches Path, Closure is called with one extra argument: the parsed HTTP request. Options is a list containing the following options:

authentication(+Type): Demand authentication. Authentication methods are pluggable. The library http_authenticate.pl provides a plugin for user/password based Basic HTTP authentication.
chunked: Use Transfer-encoding: chunked if the client allows for it.
content_type(+Term): Specifies the content-type of the reply. This value is currently not used by this library. It enhances the reflexive capabilities of this library through http_current_handler/3.
id(+Term): Identifier of the handler. The default identifier is the predicate name. Used by http_location_by_id/2.
hide_children(+Bool): If true on a prefix-handler (see prefix), possible children are masked. This can be used to (temporary) overrule part of the tree.
prefix: Call Pred on any location that is a specialisation of Path. If multiple handlers match, the one with the longest path is used.
priority(+Integer): If two handlers handle the same path, the one with the highest priority is used. If equal, the last registered is used. Please be aware that the order of clauses in multifile predicates can change due to reloading files. The default priority is 0 (zero).
spawn(+SpawnOptions): Run the handler in a seperate thread. If SpawnOptions is an atom, it is interpreted as a thread pool name (see create_thread_pool/3). Otherwise the options are passed to http_spawn/2 and from there to thread_create/3. These options are typically used to set the stack limits.
time_limit(+Spec): One of infinite, default or a positive number (seconds)

Note that http_handler/3 is normally invoked as a directive and processed using term-expansion. Using term-expansion ensures proper update through make/0 when the specification is modified. We do not expand when the cross-referencer is running to ensure proper handling of the meta-call.

Errors: existence_error(http_location, Location)
See also: http_reply_file/3 and http_redirect/3 are generic handlers to serve files and achieve redirects.

[det]http_delete_handler(+Spec)

Delete handler for Spec. Typically, this should only be used for handlers that are registered dynamically. Spec is one of:

id(Id): Delete a handler with the given id. The default id is the handler-predicate-name.
path(Path): Delete handler that serves the given path.

[det]http_dispatch(Request)

Dispatch a Request using http_handler/3 registrations.

[semidet]http_current_handler(+Location, :Closure)

[nondet]http_current_handler(-Location, :Closure)

True if Location is handled by Closure.

[semidet]http_current_handler(+Location, :Closure, -Options)

[nondet]http_current_handler(?Location, :Closure, ?Options)

Resolve the current handler and options to execute it.

[det]http_location_by_id(+ID, -Location)

Find the HTTP Location of handler with ID. If the setting (see setting/2) http:prefix is active, Location is the handler location prefixed with the prefix setting. Handler IDs can be specified in two ways:

id(ID): If this appears in the option list of the handler, this it is used and takes preference over using the predicate.
M : PredName: The module-qualified name of the predicate.
PredName: The unqualified name of the predicate.

Errors: existence_error(http_handler_id, Id).

http_link_to_id(+HandleID, +Parameters, -HREF)

HREF is a link on the local server to a handler with given ID, passing the given Parameters.

[det]http_reply_file(+FileSpec, +Options, +Request)

Options is a list of

cache(+Boolean): If true (default), handle If-modified-since and send modification time.
mime_type(+Type): Overrule mime-type guessing from the filename as provided by file_mime_type/2.
unsafe(+Boolean): If false (default), validate that FileSpec does not contain references to parent directories. E.g., specifications such as www('../../etc/passwd') are not allowed.

If caching is not disabled, it processed the request headers If-modified-since and Range.

throws: - http_reply(not_modified)
- http_reply(file(MimeType, Path))

[det]http_safe_file(+FileSpec, +Options)

True if FileSpec is considered safe. If it is an atom, it cannot be absolute and cannot have references to parent directories. If it is of the form alias(Sub), than Sub cannot have references to parent directories.

Errors: - instantiation_error
- permission_error(read, file, FileSpec)

[det]http_redirect(+How, +To, +Request)

Redirect to a new location. The argument order, using the Request as last argument, allows for calling this directly from the handler declaration:

:- http_handler(root(.),
                http_redirect(moved, myapp('index.html')),
                []).

`How`	is one of `moved`, `moved_temporary` or `see_also`
`To`	is an atom, a aliased path as defined by http_absolute_location/3. or a term location_by_id(Id). If `To` is not absolute, it is resolved relative to the current location.