The HTTP server infra structure consists of a number of small modular
libraries that are combined into library(http/http_server).
These modules are:
library(http/thread_httpd)library(http/http_dyn_workers)library(http/http_wrapper)library(http/http_dispatch)library(http/http_parameters)library(http/html_write)current_output to XML-based templates
(PWP).library(http/http_json)
Most server implementation simply load the library(http/http_server)
library, which loads the above modules and reexports all predicates
except for those used for internal communication and older deprecated
predicates. Specific use cases may load a subset of the individual
libraries and may decide to replace one or more of them.
A typical skeleton for building a server is given below. If this file
is loaded as main file (using e.g., swipl server.pl) it
creates a simple server that listens on port 8080. If the root is
accessed it redirects to the home page and shows Hello world!.
:- use_module(library(http/http_server)).
:- initialization
http_server([port(8080)]).
:- http_handler(root(.),
http_redirect(moved, location_by_id(home_page)),
[]).
:- http_handler(root(home), home_page, []).
home_page(_Request) :-
reply_html_page(
title('Demo server'),
[ h1('Hello world!')
]).
The handler (e.g., home_page/1 above) is called with the
parsed request (see section 3.13) as
argument and
current_output set to a temporary buffer. Its task is
closely related to the task of a CGI script; it must write a header
declaring at least the Content-type field and a body. Below
is a simple body writing the request as an HTML table.3Note
that writing an HTML reply this way is deprecated. In fact, the code is
subject to injection attacks as the HTTP request field values
are literally injected in the output while HTML reserved characters
should be properly escaped.
reply(Request) :-
format('Content-type: text/html~n~n', []),
format('<html>~n', []),
format('<table border=1>~n'),
print_request(Request),
format('~n</table>~n'),
format('</html>~n', []).
print_request([]).
print_request([H|T]) :-
H =.. [Name, Value],
format('<tr><td>~w<td>~w~n', [Name, Value]),
print_request(T).
The infrastructure recognises the header fields described below.
Other header lines are passed verbatim to the client. Typical examples
are
Set-Cookie and authentication headers (see section
3.7).
text/* or the type matches with UTF-8
(case insensitive), the server uses UTF-8 encoding. The user may force
UTF-8 encoding for arbitrary content types by adding ;
charset=UTF-8 to the end of the Content-type header.chunked option in http_handler/3.Status header to force
a
redirect response to the given URL. The message body
must be empty. Handling this header is primarily intended for
compatibility with the CGI conventions. Prolog code should use
http_redirect/3.Location, where Status
must be one of 301 (moved), 302 (moved temporary, default) or 303 (see
other). Using the status field also allows for formulating replies such
as 201 (created).
Note that the handler may send any type of document instead of HTML.
After the header has been written, the encoding of the
current_output stream encoding is established as follows:
text/* the stream is switched to
UTF-8 encoding. If the content type does not provide attributes, ; charset=UTF-8
is added.UTF-8 the stream is switched
to UTF-8 encoding.http_header. The current list deals with JSON, Turtle
and SPARQL.
Besides returning a page by writing it to the current output stream,
the server goal can raise an exception using throw/1
to generate special pages such as not_found, moved,
etc. The defined exceptions are:
http_reply(Reply, HdrExtra,[]).http_reply(Reply, [],[]).http_reply(not_modified,[]). This exception
is for backward compatibility and can be used by the server to indicate
the referenced resource has not been modified since it was requested
last time.
In addition, the normal "200 OK" reply status may be
overruled by writing a CGI Status header prior to the
remainder of the message. This is particularly useful for defining REST
APIs. The following handler replies with a "201 Created"
header:
handle_request(Request) :-
process_data(Request, Id), % application predicate
format('Status: 201~n'),
format('Content-type: text/plain~n~n'),
format('Created object as ~q~n', [Id]).
Most code doesn't need to use this directly; instead use
library(http/http_server), which combines this library with
the typical HTTP libraries that most servers need.
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) :-
...
'/home.html' or a term
Alias(Relative). Where Alias is associated with a concrete path using http:location/3
and resolved using http_absolute_location/3. Relative
can be a single atom or a term‘Segment1/Segment2/...`, where each
element is either an atom or a variable. If a segment is a variable it
matches any segment and the binding may be passed to the closure. If the
last segment is a variable it may match multiple segments. This allows
registering REST paths, for example:
:- http_handler(root(user/User), user(Method, User),
[ method(Method),
methods([get,post,put])
]).
user(get, User, Request) :-
...
user(post, User, Request) :-
...
If an HTTP request arrives at the server that matches Path, Closure is called as below, where Request is the parsed HTTP request.
call(Closure, Request)
Options is a list containing the following options:
http_authenticate.pl
provides a plugin for user/password based Basic HTTP
authentication.Transfer-encoding: chunked if the client allows for it.true on a prefix-handler (see prefix), possible children
are masked. This can be used to (temporary) overrule part of the tree.methods([Method]). Using method(*) allows for
all methods.
:- http_handler(/, http_404([index('index.html')]),
[spawn(my_pool),prefix]).
infinite, default or a positive number
(seconds). If
default, the value from the setting http:time_limit
is taken. The default of this setting is 300 (5 minutes). See
setting/2.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.
existence_error(http_location, Location) permission_error(http_method, Method, Location)
path member of Request.
If multiple handlers match due to the prefix option or
variables in path segments (see http_handler/3),
the longest specification is used. If multiple specifications of equal
length match the one with the highest priority is used.method member of the
Request or throw permission_error(http_method, Method, Location)http_reply(Term, ExtraHeader, Context)
exceptions.method(Method) as one of the options.call(Goal, Request0, Request, Options)
If multiple goals are registered they expand the request in a pipeline starting with the expansion hook with the lowest rank.
Besides rewriting the request, for example by validating the user identity based on HTTP authentication or cookies and adding this to the request, the hook may raise HTTP exceptions to indicate a bad request, permission error, etc. See http_status_reply/4.
Initially, auth_expansion/3 is
registered with rank 100 to deal with the older http:authenticate/3
hook.
id(ID) appears in the option list of the handler, ID
it is used and takes preference over using the predicate.Module:Pred
If the handler is declared with a pattern, e.g., root(user/User),
the location to access a particular user may be accessed using
e.g., user('Bob'). The number of arguments to the compound
term must match the number of variables in the path pattern.
A plain atom ID can be used to find a handler with a
pattern. The returned location is the path up to the first variable,
e.g.,
/user/ in the example above.
User code is adviced to use http_link_to_id/3 which can also add query parameters to the URL. This predicate is a helper for http_link_to_id/3.
existence_error(http_handler_id, Id).library(http/html_write)
construct
location_by_id(ID) or its abbreviation #(ID)root(user_details))
is irrelevant in this equation and HTTP locations can thus be moved
freely without breaking this code fragment.
:- http_handler(root(user_details), user_details, []).
user_details(Request) :-
http_parameters(Request,
[ user_id(ID)
]),
...
user_link(ID) -->
{ user_name(ID, Name),
http_link_to_id(user_details, [id(ID)], HREF)
},
html(a([class(user), href(HREF)], Name)).
| HandleID | is either an atom, possibly module qualified predicate or a compound term if the hander is defined using a pattern. See http_handler/3 and http_location_by_id/2. |
| Parameters | is one of
|
true (default), handle If-modified-since and send
modification time.true (default false) and, in addition to
the plain file, there is a .gz file that is not older than
the plain file and the client acceps gzip encoding, send
the compressed file with Transfer-encoding: gzip.true (default false) the system maintains
cached gzipped files in a directory accessible using the file search
path http_gzip_cache and serves these similar to the static_gzip(true)
option. If the gzip file does not exist or is older than the input the
file is recreated.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 processes the request headers
If-modified-since and Range.
http_reply(not_modified) http_reply(file(MimeType, Path))alias(Sub), than Sub cannot have
references to parent directories.
permission_error(read, file, FileSpec)
:- http_handler(root(.),
http_redirect(moved, myapp('index.html')),
[]).
| How | is one of moved, moved_temporary
or see_other |
| To | is an atom, a aliased path as defined by
http_absolute_location/3.
or a term location_by_id(Id) or its abbreviations #(Id)
or #(Id)+Parameters. If To is not absolute, it
is resolved relative to the current location. |
http_reply(not_found(Path))"HTTP 101 Switching Protocols" reply. After sending
the reply, the HTTP library calls call(Goal, InStream, OutStream),
where InStream and OutStream are the raw streams to the HTTP client.
This allows the communication to continue using an an alternative
protocol.
If Goal fails or throws an exception, the streams are
closed by the server. Otherwise Goal is responsible for
closing the streams. Note that Goal runs in the HTTP handler
thread. Typically, the handler should be registered using the spawn
option if http_handler/3 or Goal
must call thread_create/3 to allow the
HTTP worker to return to the worker pool.
The streams use binary (octet) encoding and have their I/O timeout set to the server timeout (default 60 seconds). The predicate set_stream/2 can be used to change the encoding, change or cancel the timeout.
This predicate interacts with the server library by throwing an exception.
The following options are supported:
headers(+Headers).
This module provides a simple API to generate an index for a physical directory. The index can be customised by overruling the dirindex.css CSS file and by defining additional rules for icons using the hook http:file_extension_icon/2.
The calling conventions allows for direct calling from http_handler/3.
//name (default), size or time.ascending. The altenative is
descendingabsolute_file_name(icons(IconName), Path, []).
Although the SWI-Prolog Web Server is intended to serve documents
that are computed dynamically, serving plain files is sometimes
necessary. This small module combines the functionality of http_reply_file/3
and
http_reply_dirindex/3
to act as a simple web-server. Such a server can be created using the
following code sample, which starts a server at port 8080 that serves
files from the current directory (’.’). Note that the
handler needs a prefix option to specify that it must
handle all paths that begin with the registed location of the handler.
:- use_module(library(http/http_server)).
:- use_module(library(http/http_files)).
:- http_handler(root(.), http_reply_from_files('.', []), [prefix]).
:- initialization(http_server([port(8080)]), main).
indexes to locate an index file (see below) or
uses http_reply_dirindex/3
to create a listing of the directory.
Options:
['index.html'].fail makes the handler fail silently. 404
make the handler call http_404/2.
Default is fail.
Note that this handler must be tagged as a prefix
handler (see
http_handler/3 and module
introduction). This also implies that it is possible to override more
specific locations in the hierarchy using http_handler/3
with a longer path-specifier.
When using http_handler/3
to bind this predicate to an HTTP location, make sure it is bound to a
location that ends in a /. When using http:location/3
to define symbolic names to HTTP locations this is written as
:- http_handler(aliasname(.), http_reply_from_files(srcdir, []), [prefix]).| Dir | is either a directory or an path-specification as used by absolute_file_name/3. This option provides great flexibility in (re-)locating the physical files and allows merging the files of multiple physical locations into one web-hierarchy by using multiple user:file_search_path/2 clauses that define the same alias. |
Content-type from the file name.
This library defines session management based on HTTP cookies.
Session management is enabled simply by loading this module. Details can
be modified using http_set_session_options/1.
By default, this module creates a session whenever a request is
processes that is inside the hierarchy defined for session handling (see
path option in
http_set_session_options/1).
Automatic creation of a session can be stopped using the option create(noauto).
The predicate
http_open_session/2 must
be used to create a session if noauto is enabled. Sessions
can be closed using http_close_session/1.
If a session is active, http_in_session/1 returns the current session and http_session_assert/1 and friends maintain data about the session. If the session is reclaimed, all associated data is reclaimed too.
Begin and end of sessions can be monitored using library(broadcast).
The broadcasted messages are:
For example, the following calls end_session(SessionId)
whenever a session terminates. Please note that sessions ends are not
scheduled to happen at the actual timeout moment of the session.
Instead, creating a new session scans the active list for timed-out
sessions. This may change in future versions of this library.
:- listen(http_session(end(SessionId, Peer)),
end_session(SessionId)).
0
(zero) disables timeout.swipl_session./. Cookies are only sent if the HTTP request path is a
refinement of Path.auto
(default), which creates a session if there is a request whose path
matches the defined session path or noauto, in which cases
sessions are only created by calling
http_open_session/2
explicitely.active, which starts a thread
that performs session cleanup at close to the moment of the timeout or passive,
which runs session GC when a new session is created.none, lax (default), or strict
- The SameSite attribute prevents the CSRF vulnerability. strict has
best security, but prevents links from external sites from operating
properly. lax stops most CSRF attacks against REST endpoints but rarely
interferes with legitimage operations. none removes the
samesite attribute entirely. __Caution: The value none
exposes the entire site to CSRF attacks.
In addition, extension libraries can define session_option/2
to make this predicate support more options. In particular,
library(http/http_redis_plugin) defines the following
additional options:
'swipl:http:session'http_session_set(Setting).timeout.
permission_error(set, http_session, Setting) if setting a
setting that is not supported on per-session basis.| SessionId | is an atom. |
existence_error(http_session, _)session(ID) from the
current HTTP request (see http_current_request/1).
The value is cached in a backtrackable global variable http_session_id.
Using a backtrackable global variable is safe because continuous worker
threads use a failure driven loop and spawned threads start without any
global variables. This variable can be set from the commandline to fake
running a goal from the commandline in the context of a session.
noauto. Options:
true (default false) and the current
request is part of a session, generate a new session-id. By default,
this predicate returns the current session as obtained with
http_in_session/1.permission_error(open, http_session, CGI) if this call is
used after closing the CGI header.create option. existence_error(http_session,_)http_session(end(SessionId, Peer))
The broadcast is done before the session data is destroyed and the listen-handlers are executed in context of the session that is being closed. Here is an example that destroys a Prolog thread that is associated to a thread:
:- listen(http_session(end(SessionId, _Peer)),
kill_session_thread(SessionID)).
kill_session_thread(SessionID) :-
http_session_data(thread(ThreadID)),
thread_signal(ThreadID, throw(session_closed)).
Succeed without any effect if SessionID does not refer to an active session.
If http_close_session/1
is called from a handler operating in the current session and the CGI
stream is still in state
header, this predicate emits a Set-Cookie to
expire the cookie.
type_error(atom, SessionID)library(http/http_redis_plugin), storing all session data
in a redis database.
This small module allows for enabling Cross-Origin Resource Sharing (CORS) for a specific request. Typically, CORS is enabled for API services that you want to have useable from browser client code that is loaded from another domain. An example are the LOD and SPARQL services in ClioPatria.
Because CORS is a security risc (see references), it is disabled by default. It is enabled through the setting http:cors. The value of this setting is a list of domains that are allowed to access the service. Because * is used as a wildcard match, the value [*] allows access from anywhere.
Services for which CORS is relevant must call cors_enable/0
as part of the HTTP response, as shown below. Note that cors_enable/0
is a no-op if the setting http:cors is set to the empty list ([]).
my_handler(Request) :-
....,
cors_enable,
reply_json(Response, []).
If a site uses a Preflight OPTIONS request to
find the server's capabilities and access politics, cors_enable/2
can be used to formulate an appropriate reply. For example:
my_handler(Request) :-
option(method(options), Request), !,
cors_enable(Request,
[ methods([get,post,delete])
]),
format('~n'). % 200 with empty body
Access-Control-Allow-Origin using
domains from the setting http:cors. This this setting is []
(default), nothing is written. This predicate is typically used for
replying to API HTTP-request (e.g., replies to an AJAX request that
typically serve JSON or XML).OPTIONS request. Request
is the HTTP request. Options provides:
GET,
only allowing for read requests.
Both methods and headers may use Prolog friendly syntax, e.g.,
get for a method and content_type for a
header.
This module provides the basics to validate an HTTP Authorization
header. User and password information are read from a Unix/Apache
compatible password file.
This library provides, in addition to the HTTP authentication, predicates to read and write password files.
Basic authetication and verify the password from PasswordFile. PasswordFile
is a file holding usernames and passwords in a format compatible to Unix
and Apache. Each line is record with : separated fields.
The first field is the username and the second the password hash.
Password hashes are validated using crypt/2.Successful authorization is cached for 60 seconds to avoid overhead of decoding and lookup of the user and password data.
http_authenticate/3 just validates the header. If authorization is not provided the browser must be challenged, in response to which it normally opens a user-password dialogue. Example code realising this is below. The exception causes the HTTP wrapper code to generate an HTTP 401 reply.
( http_authenticate(basic(passwd), Request, Fields) -> true ; throw(http_reply(authorise(basic, Realm))) ).
| Fields | is a list of fields from the password-file entry. The first element is the user. The hash is skipped. |
Authorization header. Data is a
term
Method(User, Password)
where Method is the (downcased) authorization method (typically
basic), User is an atom holding the user name and Password
is a list of codes holding the password
| Fields | are the fields from the password file File, converted using name/2, which means that numeric values are passed as numbers and other fields as atoms. The password hash is the first element of Fields and is a string. |
passwd(User, Hash, Fields)
passwd(User, Hash, Fields)
library(http_dispatch) to perform basic HTTP
authentication.
This predicate throws http_reply(authorise(basic, Realm)).
| AuthData | must be a term basic(File, Realm) |
| Request | is the HTTP request |
| Fields | describes the authenticated user with
the option
user(User) and with the option user_details(Fields)
if the password file contains additional fields after the user and
password. |
This library implements HTTP Digest Authentication as per RFC2617. Unlike Basic Authentication, digest authentication is based on challenge-reponse and therefore does not need to send the password over the (insecure) connection. In addition, it provides a count mechanism that ensure that old credentials cannot be reused, which prevents attackers from using old credentials with a new request. Digest authentication have the following advantages and disadvantages:
And, of course, the connection itself remains insecure. Digest based authentication is a viable alternative if HTTPS is not a good option and security of the data itself is not an issue.
This library acts as plugin for library(http/http_dispatch),
where the registered handler (http_handler/3)
can be given the option below to initiate digest authentication.
authentication(digest(PasswdFile, Realm))
Above, PasswdFile is a file containing lines of the from
below, where PasswordHash is computed using http_digest_password_hash/4.
See also
library(http/http_authenticate), http_read_passwd_file/2
and
http_write_passwd_file/2.
User ":" PasswordHash (":" Extra)*
This library also hooks into library(http/http_open) if
the option
authorization(digest(User, Password)) is given.
//WWW-Authenticate: Digest
header field.WWW-Authenticate header into a
list of Name(Value) terms./'GET'| Challenge | is a list Name(Value), normally
from
http_parse_digest_challenge/2.
Must contain
realm and nonce. Optionally contains
opaque. |
| User | is the user we want to authenticated |
| Password | is the user's password |
| Options | provides additional options |
<user>:<realm>:<password>.
The inexpensive MD5 algorithm makes the hash sensitive to brute force attacks while the lack of seeding make the hashes sensitive for rainbow table attacks, although the value is somewhat limited because the realm and user are part of the hash.
library(http_dispatch) to perform basic HTTP
authentication. Note that we keep the authentication details cached to
avoid a‘nonce-replay’error in the case that the application
tries to verify multiple times.
This predicate throws http_reply(authorise(digest(Digest)))
| Digest | is a term digest(File, Realm, Options) |
| Request | is the HTTP request |
| Fields | describes the authenticated user with
the option
user(User) and with the option user_details(Fields)
if the password file contains additional fields after the user and
password. |
authorization(AuthData) and Out is a
stream on which to write additional HTTP headers.request_header(authorization=Digest) header to Options,
causing
http_open/3 to retry the request
with the additional option.
Most code doesn't need to use this directly; instead use
library(http/http_server), which combines this library with
the typical HTTP libraries that most servers need.
This module defines hooks into the HTTP framework to dynamically schedule worker threads. Dynamic scheduling relieves us from finding a good value for the size of the HTTP worker pool.
The decision to add a worker follows these rules:
The policy depends on three settings:
http:max_workershttp:worker_idle_limithttp:max_load__http_scheduler as the hook is called in time critical
code.
Server-Sent Events allows for setting up a simple event stream from the server to the client. It can serve roles similar to long polling and web sockets, enabling the server to notify its clients on some event. Long polling uses a normal HTTP (usually) GET request that blocks for a long time on the server. The server finishes the request when it wants to notify the client or after some time (e.g., a minute) to avoid a timeout on the client or some proxy. After receiving an event or timeout, the client repeats the request. Web sockets upgrade a the socket used for a normal HTTP request to create a bi-directional open communication channel that exchanges encapsulated messages in both directions. Server-Sent Events open a normal HTTP channel over which the server can sent simple text messages using a format similar to the HTTP header: a sequence of Name: Value lines followed by two newlines. Unlike long polling, the request does not complete after a message.
Following the MDN documentation above, and SSE request can be served using the simple example below that generates an event, counting every minute. Note the handler declaration that processes the request on a new thread and disables timeout for this location. Note that this implementation uses a thread per client. This design limits the scalability.
:- http_handler(root(events), events,
[ spawn([]),
time_limit(infinite)
]).
events(_Request) :-
format('X-Accel-Buffering: no\r\n\c
Content-Type: text/event-stream\r\n\c
Cache-Control: no-cache\r\n\r\n'),
between(1, infinite, Min),
format('event: minute~n'),
format('data: {"minute": ~d}~n~n', [Min]),
flush_output,
sleep(60),
fail.
Of course, rather than sleep/1 to decide when to fire the next event this thread typically has to wait for events in the application. This can be achieved using thread_wait/2 or message queues.
It is possible to create arbitrary error pages for responses
generated when a http_reply term is thrown. Currently this is only
supported for status 403 (authentication required). To do this,
instead of throwing http_reply(authorise(Term)) throw
http_reply(authorise(Term), [], Key), where Key
is an arbitrary term relating to the page you want to generate. You must
then also define a clause of the multifile predicate http:status_page_hook/3:
http_reply
exception or the HTTP status code, i.e., the hook is called twice. New
code should using the Term. Context is the third argument of
the http_reply exception which was thrown, and CustomHTML is a list of
HTML tokens. A page equivalent to the default page for 401 is generated
by the example below.
:- multifile http:status_page_hook/3.
http:status_page_hook(authorise(Term), _Context, HTML) :-
phrase(page([ title('401 Authorization Required')
],
[ h1('Authorization Required'),
p(['This server could not verify that you ',
'are authorized to access the document ',
'requested. Either you supplied the wrong ',
'credentials (e.g., bad password), or your ',
'browser doesn\'t understand how to supply ',
'the credentials required.'
]),
\address
]),
HTML).
This library implements the OpenID protocol (http://openid.net/). OpenID is a protocol to share identities on the network. The protocol itself uses simple basic HTTP, adding reliability using digitally signed messages.
Steps, as seen from the consumer (or relying partner).
openid_identifieropenid_identifier and lookup
<link rel="openid.server" href="server">checkid_setup,
asking to validate the given OpenID.
A consumer (an application that allows OpenID login) typically
uses this library through openid_user/3.
In addition, it must implement the hook http_openid:openid_hook(trusted(OpenId, Server))
to define accepted OpenID servers. Typically, this hook is used to
provide a white-list of acceptable servers. Note that accepting any
OpenID server is possible, but anyone on the internet can setup a dummy
OpenID server that simply grants and signs every request. Here is an
example:
:- multifile http_openid:openid_hook/1.
http_openid:openid_hook(trusted(_, OpenIdServer)) :-
( trusted_server(OpenIdServer)
-> true
; throw(http_reply(moved_temporary('/openid/trustedservers')))
).
trusted_server('http://www.myopenid.com/server').
By default, information who is logged on is maintained with the
session using http_session_assert/1
with the term openid(Identity). The hooks
login/logout/logged_in can be used to provide alternative administration
of logged-in users (e.g., based on client-IP, using cookies, etc.).
To create a server, you must do four things: bind the handlers
openid_server/2 and openid_grant/1
to HTTP locations, provide a user-page for registered users and define
the grant(Request, Options) hook to verify your users. An
example server is provided in in
<plbase>/doc/packages/examples/demo_openid.pl
handler(Request) :-
openid_user(Request, OpenID, []),
...
If the user is not yet logged on a sequence of redirects will follow:
verify, which calls openid_verify/2.
Options:
//img structures where the href
points to an OpenID 2.0 endpoint. These buttons are displayed below the
OpenID URL field. Clicking the button sets the URL field and submits the
form. Requires Javascript support.
If the href is relative, clicking it opens the
given location after adding’openid.return_to’and‘stay’.
true, show a checkbox that allows the user to stay
logged on.http_dispatch.pl. Options
processes:
openid.trust_root attribute. Defaults to the
root of the current server (i.e., http://host[.port]/).openid.realm attribute. Default is the
trust_root.
The OpenId server will redirect to the openid.return_to
URL.
http_reply(moved_temporary(Redirect))| OpenIDLogin | ID as typed by user (canonized) |
| OpenID | ID as verified by server |
| Server | URL of the OpenID server |
global(true).
After openid_verify/2 has
redirected the browser to the OpenID server, and the OpenID
server did its magic, it redirects the browser back to this address. The
work is fairly trivial. If
mode is cancel, the OpenId server denied. If id_res,
the OpenId server replied positive, but we must verify what the server
told us by checking the HMAC-SHA signature.
This call fails silently if their is no openid.mode
field in the request.
openid(cancel) if request was cancelled by the OpenId
server openid(signature_mismatch) if the HMAC signature check
failedyes, check the authority (typically the password) and if
all looks good redirect the browser to ReturnTo, adding the OpenID
properties needed by the Relying Party to verify the login.openid_associate(URL, Handle, Assoc, []).
http://specs.openid.net/auth/2.0 (default) or
http://openid.net/signon/1.1.
The library library(http/http_parameters) provides two
predicates to fetch HTTP request parameters as a type-checked list
easily. The library transparently handles both GET and POST requests. It
builds on top of the low-level request representation described in
section 3.13.
If a parameter is missing the exception
error(
is thrown which. If the argument cannot be converted to the requested
type, a
existence_error(http_parameter, Name), _)error( is
raised, where the error context indicates the HTTP parameter. If not
caught, the server translates both errors into a existence_error(Type, Value), _)400 Bad request
HTTP message.
Options fall into three categories: those that handle presence of the parameter, those that guide conversion and restrict types and those that support automatic generation of documention. First, the presence-options:
default and optional are
ignored and the value is returned as a list. Type checking options are
processed on each value.list(Type).The type and conversion options are given below. The type-language can be extended by providing clauses for the multifile hook http:convert_parameter/3.
;(Type1, Type2)(nonneg;oneof([infinite])) to
specify an integer or a symbolic value.
The last set of options is to support automatic generation of HTTP
API documentation from the sources.4This
facility is under development in ClioPatria; see http_help.pl.
Below is an example
reply(Request) :-
http_parameters(Request,
[ title(Title, [ optional(true) ]),
name(Name, [ length >= 2 ]),
age(Age, [ between(0, 150) ])
]),
...
Same as http_parameters(Request, Parameters,[])
call(Goal, +ParamName, -Options) to find the options.
Intended to share declarations over many calls to http_parameters/3.
Using this construct the above can be written as below.
reply(Request) :-
http_parameters(Request,
[ title(Title),
name(Name),
age(Age)
],
[ attribute_declarations(param)
]),
...
param(title, [optional(true)]).
param(name, [length >= 2 ]).
param(age, [integer]).
The body-code (see section 3.1) is
driven by a Request. This request is generated from http_read_request/2
defined in
library(http/http_header).
Name(Value)
elements. It provides a number of predefined elements for the result of
parsing the first line of the request, followed by the additional
request parameters. The predefined fields are:
Host: Host, Host is
unified with the host-name. If Host is of the format <host>:<port>
Host only describes <host> and a field port(Port)
where
Port is an integer is added.delete, get, head,
options, patch, post, put,
trace). This field is present if the header has been parsed
successfully.ip(A,B,C,D) containing the IP
address of the contacting host.host for details.?The URL specification does not demand the query part to be of the form name=value. If the field is syntactically incorrect, ListOfNameValue is bound the the empty list ([]).
HTTP/Major.Minor
version indicator this element indicate the HTTP version of the peer.
Otherwise this field is not present.Cookie line, the value of the
cookie is broken down in Name=Value pairs, where
the
Name is the lowercase version of the cookie name as used for
the HTTP fields.SetCookie line, the cookie field
is broken down into the Name of the cookie, the Value
and a list of Name=Value pairs for additional
options such as expire, path, domain
or secure.
If the first line of the request is tagged with
HTTP/Major.Minor, http_read_request/2
reads all input upto the first blank line. This header consists of
Name:Value fields. Each such field appears as a
term
Name(Value) in the Request, where Name
is canonicalised for use with Prolog. Canonisation implies that the
Name is converted to lower case and all occurrences of the
-_. The value
for the
Content-length fields is translated into an integer.
Here is an example:
?- http_read_request(user_input, X).
|: GET /mydb?class=person HTTP/1.0
|: Host: gollem
|:
X = [ input(user),
method(get),
search([ class = person
]),
path('/mydb'),
http_version(1-0),
host(gollem)
].
Where the HTTP GET operation is intended to get a
document, using a path and possibly some additional search
information, the POST operation is intended to hand
potentially large amounts of data to the server for processing.
The Request parameter above contains the term method(post).
The data posted is left on the input stream that is available through
the term input(Stream) from the Request header.
This data can be read using http_read_data/3
from the HTTP client library. Here is a demo implementation simply
returning the parsed posted data as plain text (assuming pp/1
pretty-prints the data).
reply(Request) :-
member(method(post), Request), !,
http_read_data(Request, Data, []),
format('Content-type: text/plain~n~n', []),
pp(Data).
If the POST is initiated from a browser, content-type is generally
either application/x-www-form-urlencoded or
multipart/form-data.
The functionality of the server should be defined in one Prolog file (of course this file is allowed to load other files). Depending on the wanted server setup this‘body’is wrapped into a small Prolog file combining the body with the appropriate server interface. There are three supported server-setups. For most applications we advise the multi-threaded server. Examples of this server architecture are the PlDoc documentation system and the SeRQL Semantic Web server infrastructure.
All the server setups may be wrapped in a reverse proxy to make them available from the public web-server as described in section 3.14.7.
library(thread_httpd) for a multi-threaded
serverThis server is harder to debug due to the involved threading, although the GUI tracer provides reasonable support for multi-threaded applications using the tspy/1 command. It can provide fast communication to multiple clients and can be used for more demanding servers.
library(inetd_httpd) for server-per-clientThis server is very hard to debug as the server is not connected to the user environment. It provides a robust implementation for servers that can be started quickly.
All the server interfaces provide http_server(:Goal, +Options)
to create the server. The list of options differ, but the servers share
common options:
The library(http/thread_httpd.pl) provides the
infrastructure to manage multiple clients using a pool of worker-threads.
This realises a popular server design, also seen in Java Tomcat and
Microsoft .NET. As a single persistent server process maintains
communication to all clients startup time is not an important issue and
the server can easily maintain state-information for all clients.
In addition to the functionality provided by the inetd server, the
threaded server can also be used to realise an HTTPS server exploiting
the library(ssl) library. See option ssl(+SSLOptions)
below.
port(?Port)
option to specify the port the server should listen to. If Port
is unbound an arbitrary free port is selected and Port is
unified to this port-number. The server consists of a small Prolog
thread accepting new connection on Port and dispatching these
to a pool of workers. Defined Options are:
infinite,
a worker may wait forever on a client that doesn't complete its request.
Default is 60 seconds.https:// protocol. SSL
allows for encrypted communication to avoid others from tapping the wire
as well as improved authentication of client and server. The SSLOptions
option list is passed to ssl_context/3.
The port option of the main option list is forwarded to the SSL layer.
See the library(ssl) library for details.http or https.This can be used to tune the number of workers for performance. Another possible application is to reduce the pool to one worker to facilitate easier debugging.
pool(Pool) or to thread_create/3
of the pool option is not present. If the dispatch module is used (see section
3.2), spawning is normally specified as an option to the http_handler/3
registration.
We recomment the use of thread pools. They allow registration of a set of threads using common characteristics, specify how many can be active and what to do if all threads are active. A typical application may define a small pool of threads with large stacks for computation intensive tasks, and a large pool of threads with small stacks to serve media. The declaration could be the one below, allowing for max 3 concurrent solvers and a maximum backlog of 5 and 30 tasks creating image thumbnails.
:- use_module(library(thread_pool)).
:- thread_pool_create(compute, 3,
[ local(20000), global(100000), trail(50000),
backlog(5)
]).
:- thread_pool_create(media, 30,
[ local(100), global(100), trail(100),
backlog(100)
]).
:- http_handler('/solve', solve, [spawn(compute)]).
:- http_handler('/thumbnail', thumbnail, [spawn(media)]).
This module provides the logic that is needed to integrate a process into the Unix service (daemon) architecture. It deals with the following aspects, all of which may be used/ignored and configured using commandline options:
port(s) to be used by the serverThe typical use scenario is to write a file that loads the following components:
In the code below, ?- [load]. loads the remainder of the
webserver code. This is often a sequence of use_module/1
directives.
:- use_module(library(http/http_unix_daemon)). :- [load].
The program entry point is http_daemon/0, declared using initialization/2. This may be overruled using a new declaration after loading this library. The new entry point will typically call http_daemon/1 to start the server in a preconfigured way.
:- use_module(library(http/http_unix_daemon)).
:- initialization(run, main).
run :-
...
http_daemon(Options).
Now, the server may be started using the command below. See http_daemon/0 for supported options.
% [sudo] swipl mainfile.pl [option ...]
Below are some examples. Our first example is completely silent,
running on port 80 as user www.
% swipl mainfile.pl --user=www --pidfile=/var/run/http.pid
Our second example logs HTTP interaction with the syslog daemon for
debugging purposes. Note that the argument to --debug= is a
Prolog term and must often be escaped to avoid misinterpretation by the
Unix shell. The debug option can be repeated to log multiple debug
topics.
% swipl mainfile.pl --user=www --pidfile=/var/run/http.pid \
--debug='http(request)' --syslog=http
Broadcasting The library uses broadcast/1 to allow hooking certain events:
--http=Spec or --https=Spec is followed by
arguments for that server until the next --http=Spec or --https=Spec
or the end of the options.--http=Spec or --https=Spec appears,
one HTTP server is created from the specified parameters.
Examples:
--workers=10 --http --https --http=8080 --https=8443 --http=localhost:8080 --workers=1 --https=8443 --workers=25
--user=User
to open ports below 1000. The default port is 80. If --https
is used, the default port is 443.--ip=localhost to restrict access to connections from
localhost if the server itself is behind an (Apache) proxy server
running on the same host.
socket(s)--pwfile=File)--user. If omitted, the login
group of the target user is used.--no-fork or --fork=false, the
process runs in the foreground.|Port|BindTo:Port)]true, create at the specified or default address. Else use
the given port and interface. Thus, --http creates a server
at port 80, --http=8080 creates one at port 8080 and --http=localhost:8080
creates one at port 8080 that is only accessible from localhost.|Port|BindTo:Port)]--http, but creates an HTTPS server. Use --certfile, --keyfile, -pwfile,
--password and --cipherlist to configure SSL
for this server.--password=PW as it allows using file
protection to avoid leaking the password. The file is read before
the server drops privileges when started with the --user
option.true (default false) implies --no-fork
and presents the Prolog toplevel after starting the server.kill -HUP <pid>. Default is reload
(running make/0). Alternative is quit,
stopping the server.Other options are converted by argv_options/3 and passed to http_server/1. For example, this allows for:
http_daemon/0 is defined as
below. The start code for a specific server can use this as a starting
point, for example for specifying defaults or additional options. This
uses guided options processing from argv_options/3
from library(main). The option definitions are available as http_opt_type/3, http_opt_help/2
and
http_opt_meta/2
http_daemon :-
current_prolog_flag(argv, Argv),
argv_options(Argv, _RestArgv, Options),
http_daemon(Options).
Error handling depends on whether or not interactive(true)
is in effect. If so, the error is printed before entering the toplevel.
In non-interactive mode this predicate calls halt(1).
http_server(Handler, Options). The default is
provided by start_server/1.
All modern Unix systems handle a large number of the services they
run through the super-server inetd or one of its descendants (xinetd, systemd
etc.) Such a program reads a configuration file (for example /etc/inetd.conf)
and opens server-sockets on all ports defined in this file. As a request
comes in it accepts it and starts the associated server such that
standard I/O is performed through the socket. This approach has several
advantages:
The very small generic script for handling inetd based connections is
in inetd_httpd, defining http_server/1:
Here is the example from demo_inetd
#!/usr/bin/pl -t main -q -f
:- use_module(demo_body).
:- use_module(inetd_httpd).
main :-
http_server(reply).
With the above file installed in /home/jan/plhttp/demo_inetd,
the following line in /etc/inetd enables the server at port
4001 guarded by tcpwrappers. After modifying inetd, send the
daemon the HUP signal to make it reload its configuration.
For more information, please check inetd.conf(5).
4001 stream tcp nowait nobody /usr/sbin/tcpd /home/jan/plhttp/demo_inetd
There are rumours that inetd has been ported to Windows.
To be done.
There are several options for public deployment of a web service. The main decision is whether to run it on a standard port (port 80 for HTTP, port 443 for HTTPS) or a non-standard port such as for example 8000 or 8080. Using a standard port below 1000 requires root access to the machine, and prevents other web services from using the same port. On the other hand, using a non-standard port may cause problems with intermediate proxy- and/or firewall policies that may block the port when you try to access the service from some networks. In both cases, you can either use a physical or a virtual machine running ---for example--- under VMWARE or XEN to host the service. Using a dedicated (physical or virtual) machine to host a service isolates security threats. Isolation can also be achieved using a Unix chroot environment, which is however not a security feature.
To make several different web services reachable on the same (either standard or non-standard) port, you can use a so-called reverse proxy. A reverse proxy uses rules to relay requests to other web services that use their own dedicated ports. This approach has several advantages:
Proxy technology can be combined with isolation methods such as dedicated machines, virtual machines and chroot jails. The proxy can also provide load balancing.
Setting up an Apache reverse proxy
The Apache reverse proxy setup is really simple. Ensure the modules
proxy and proxy_http are loaded. Then add two
simple rules to the server configuration. Below is an example that makes
a PlDoc server on port 4000 available from the main Apache server at
port 80.
ProxyPass /pldoc/ http://localhost:4000/pldoc/ ProxyPassReverse /pldoc/ http://localhost:4000/pldoc/
Apache rewrites the HTTP headers passing by, but using the above
rules it does not examine the content. This implies that URLs embedded
in the (HTML) content must use relative addressing. If the locations on
the public and Prolog server are the same (as in the example above) it
is allowed to use absolute locations. I.e. /pldoc/search is
ok, but http://myhost.com:4000/pldoc/search is not.
If the locations on the server differ, locations must be relative (i.e. not
start with /
This problem can also be solved using the contributed Apache module
proxy_html that can be instructed to rewrite URLs embedded
in HTML documents. In our experience, this is not troublefree as URLs
can appear in many places in generated documents. JavaScript can create
URLs on the fly, which makes rewriting virtually impossible.
The body is called by the module library(http/http_wrapper.pl).
This module realises the communication between the I/O streams and the
body described in section 3.1. The
interface is realised by
http_wrapper/5:
’Keep-alive’ if both ends of the connection
want to continue the connection or close if either side
wishes to close the connection.
This predicate reads an HTTP request-header from In,
redirects current output to a memory file and then runs call(Goal,
Request), watching for exceptions and failure. If Goal
executes successfully it generates a complete reply from the created
output. Otherwise it generates an HTTP server error with additional
context information derived from the exception.
http_wrapper/5 supports the following options:
...,
format('Set-Cookie: ~w=~w; path=~w~n', [Cookie, SessionID, Path]),
...,
If ---for whatever reason--- the conversion is not possible it simply unifies RelPath to AbsPath.
This library finds the public address of the running server. This can
be used to construct URLs that are visible from anywhere on the
internet. This module was introduced to deal with OpenID, where a
request is redirected to the OpenID server, which in turn redirects to
our server (see http_openid.pl).
The address is established from the settings http:public_host
and
http:public_port if provided. Otherwise it is deduced from
the request.
true (default false), try to replace a
local hostname by a world-wide accessible name.This predicate performs the following steps to find the host and port:
http:public_host and http:public_portX-Forwarded-Host header, which applies if this
server runs behind a proxy.Host header, which applies for HTTP 1.1 if we
are contacted directly.| Request | is the current request. If it is left unbound, and the request is needed, it is obtained with http_current_request/1. |
Simple module for logging HTTP requests to a file. Logging is enabled
by loading this file and ensure the setting http:logfile is not the
empty atom. The default file for writing the log is httpd.log.
See
library(settings) for details.
The level of logging can be modified using the multifile predicate
http_log:nolog/1 to hide HTTP request
fields from the logfile and
http_log:password_field/1 to hide
passwords from HTTP search specifications (e.g. /topsecret?password=secret).
append mode if the file is not yet
open. The log file is determined from the setting http:logfile.
If this setting is set to the empty atom (” ), this predicate
fails.
If a file error is encountered, this is reported using print_message/2, after which this predicate silently fails. Opening is retried every minute when a new message arrives.
Before opening the log file, the message http_log_open(Term)
is broadcasted. This message allows for creating the directory,
renaming, deleting or truncating an existing log file.
server(Reason, Time).
to the logfile. This call is intended for cooperation with the Unix
logrotate facility using the following schema:
Content-type header. If the
hook succeeds, the POST data is not logged. For example, to stop logging
anything but application/json messages:
:- multifile http_log:nolog_post_content_type/1. http_log:nolog_post_content_type(Type) :- Type \= (application/json).
| Type | is a term MainType/SubType |
library(http/http_unix_daemon) is used, closing is achieved
by sending SIGHUP or SIGUSR1 to the process.library(http/http_unix_daemon) which
schedules the maintenance actions.Options:
true, rotate the log files in the background.
This must be used with a timer that broadcasts a
maintenance(_,_) message (see broadcast/1).
Such a timer is part of library(http/http_unix_daemon).
This module defines an HTTP handler for /health. The
handler returns a JSON document with elementary health statistics on the
running instance. The location can be changed using http_handler/3.
Keys may be added using additional clauses for health/2
or hidden using hide/1.
This library defines an HTTP handler and defines two multifile predicates (health/2 and hide/1) to control the information presented.
Processes an optional parameter fields to specify the
fields that should be returned. The fields content is "," or white space
delimited.
true./proc/self/fd.
Otherwise we use
stream_property/2 with the file_no(Fd)
property./proc/loadavginuse:Bytessize:Bytesinuse, but including the TCMalloc overhead and
(thus) memory that has been freed and is not (yet) reused.| Key | is the name of the JSON key. Must be an atom |
| Value | is the Prolog representation for a JSON (dict) value. |
The library library(http/http_error) defines a hook that
decorates uncaught exceptions with a stack-trace. This will generate a 500
internal server error document with a stack-trace. To enable this
feature, simply load this library. Please do note that providing error
information to the user simplifies the job of a hacker trying to
compromise your server. It is therefore not recommended to load this
file by default.
The example program calc.pl has the error handler loaded
which can be triggered by forcing a divide-by-zero in the calculator.
The library library(http/http_header) provides
primitives for parsing and composing HTTP headers. Its functionality is
normally hidden by the other parts of the HTTP server and client
libraries.
end_of_file if FdIn is at the end
of input.html_write.plfile, but do not include modification time| HdrExtra | provides additional reply-header
fields, encoded as Name(Value). It can also contain a field
content_length(-Len) to retrieve the value of the
Content-length header that is replied. |
| Code | is the numeric HTTP status code sent |
Status can be one of the following:
basic(Realm)digest(Digest)authorise(basic(Realm)). Deprecated.format('Content-type: <MIME type>~n'). This hook is
called before
mime_type_encoding/2. This default defines utf8
for JSON and Turtle derived application/ MIME types.never,
even explitic requests are ignored. If on_request, chunked
encoding is used if requested through the CGI header and allowed by the
client. If
if_possible, chunked encoding is used whenever the client
allows for it, which is interpreted as the client supporting HTTP 1.1 or
higher.
Chunked encoding is more space efficient and allows the client to start processing partial results. The drawback is that errors lead to incomplete pages instead of a nicely formatted complete page.
http_client.pl
to send the POST data to the server. Data is one of:
html(+Tokens) Result of html//1
from html_write.pljson(+Term) Posting a JSON query and processing the
JSON reply (or any other reply understood by http_read_data/3)
is simple as
http_post(URL, json(Term), Reply, []), where Term is a JSON
term as described in json.pl and reply is of the same
format if the server replies with JSON, when using module :- use_module(library(http/http_json)).
Note that the module is used in both http server and http client, see
library(http/http_json).xml(+Term) Post the result of xml_write/3
using the Mime-type
text/xmlxml(+Type, +Term) Post the result of xml_write/3
using the given Mime-type and an empty option list to xml_write/3.xml(+Type, +Term, +Options) Post the result of xml_write/3
using the given Mime-type and option list for xml_write/3.file(+File) Send contents of a file. Mime-type is
determined by
file_mime_type/2.file(+Type, +File) Send file with content of indicated
mime-type.memory_file(+Type, +Handle) Similar to file(+Type, +File),
but using a memory file instead of a real file. See new_memory_file/1.codes(+Codes) As codes(text/plain, Codes).codes(+Type, +Codes) Send Codes using the indicated
MIME-type.bytes(+Type, +Bytes) Send Bytes using the indicated
MIME-type. Bytes is either a string of character codes 0..255 or list of
integers in the range 0..255. Out-of-bound codes result in a
representation error exception.atom(+Atom) As atom(text/plain, Atom).atom(+Type, +Atom) Send Atom using the indicated
MIME-type.string(+String)string(+Type, +String) Similar to atom(Atom)
and atom(Type,Atom), accepting a SWI-Prolog string.cgi_stream(+Stream, +Len) Read the input from Stream
which, like CGI data starts with a partial HTTP header. The fields of
this header are merged with the provided HdrExtra fields. The
first Len characters of Stream are used.form(+ListOfParameter) Send data of the MIME type
application/x-www-form-urlencoded as produced by browsers issuing a POST
request from an HTML form. ListOfParameter is a list of Name=Value or
Name(Value).form_data(+ListOfData) Send data of the MIME type multipart/form-data
as produced by browsers issuing a POST request from an HTML form using
enctype multipart/form-data. ListOfData is the same as for
the List alternative described below. Below is an example. Repository,
etc. are atoms providing the value, while the last argument provides a
value from a file.
...,
http_post([ protocol(http),
host(Host),
port(Port),
path(ActionPath)
],
form_data([ repository = Repository,
dataFormat = DataFormat,
baseURI = BaseURI,
verifyData = Verify,
data = file(File)
]),
_Reply,
[]),
...,
set_cookie(Name, Value, Options).
Options is a list consisting of Name=Value or a single atom
(e.g., secure)bytes(From, To), where From is an integer
and To is either an integer or the atom end.media(Type, TypeParams, Quality, AcceptExts). The list is
sorted according to preference.disposition(Name, Attributes), where Attributes
is a list of Name=Value pairs.media(Type/SubType, Attributes), where
Attributes is a list of Name=Value pairs.As some fields are already parsed in the Request, this predicate is a no-op when called on an already parsed field.
| Value | is either an atom, a list of codes or an already parsed header value. |
syntax_error(http_timestamp(Text)) if the string cannot be
parsed.--> content_type(text/html)domain_error(http_request_line, Line)
created(Location)moved(To)moved_temporary(To)see_other(To)bad_request(ErrorTerm)authorise(AuthMethod)forbidden(URL)not_found(URL)method_not_allowed(Method,URL)not_acceptable(Why)server_error(ErrorTerm)unavailable(Why)
The hook is tried twice, first using the status term, e.g.,
not_found(URL) and than with the code, e.g. 404.
The second call is deprecated and only exists for compatibility.
| Context | is the 4th argument of http_status_reply/5,
which is invoked after raising an exception of the format
http_reply(Status, HeaderExtra, Context). The default
context is [] (the empty list). |
| HTMLTokens | is a list of tokens as produced by html//1. It is passed to print_html/2. |
library(http/html_write)
libraryProducing output for the web in the form of an HTML document is a requirement for many Prolog programs. Just using format/2 is not satisfactory as it leads to poorly readable programs generating poor HTML. This library is based on using DCG rules.
The library(http/html_write) structures the generation
of HTML from a program. It is an extensible library, providing a DCG
framework for generating legal HTML under (Prolog) program control. It
is especially useful for the generation of structured pages (e.g. tables)
from Prolog data structures.
The normal way to use this library is through the DCG html//1. This non-terminal provides the central translation from a structured term with embedded calls to additional translation rules to a list of atoms that can then be printed using print_html/[1,2].
//[]
\List
\Term
\Term but allows for invoking grammar rules in
external packages.
&<Entity>; or &#<Entity>;
if Entity is an integer. SWI-Prolog atoms and strings are
represented as Unicode. Explicit use of this construct is rarely needed
because code-points that are not supported by the output encoding are
automatically converted into character-entities.
Tag(Content)
Tag(Attributes, Content)Name(Value) or
Name=Value. Value is the atomic
attribute value but allows for a limited functional notation:
encode(Atom)location_by_id(ID)#(ID)location_by_id(ID).Name(Value). Values are encoded as in the encode option
described above.NAMES). Each value
in list is separated by a space. This is particularly useful for setting
multiple class attributes on an element. For example:
...
span(class([c1,c2]), ...),
The example below generates a URL that references the predicate
set_lang/1 in
the application with given parameters. The http_handler/3
declaration binds /setlang to the predicate set_lang/1
for which we provide a very simple implementation. The code between ...
is part of an HTML page showing the english flag which, when pressed,
calls set_lang(Request) where Request contains
the search parameter lang = en. Note that the
HTTP location (path) /setlang can be moved without
affecting this code.
:- http_handler('/setlang', set_lang, []).
set_lang(Request) :-
http_parameters(Request,
[ lang(Lang, [])
]),
http_session_retractall(lang(_)),
http_session_assert(lang(Lang)),
reply_html_page(title('Switched language'),
p(['Switch language to ', Lang])).
...
html(a(href(location_by_id(set_lang) + [lang(en)]),
img(src('/www/images/flags/en.png')))),
...
//DOCTYPE declaration. HeadContent are elements to
be placed in the head element and BodyContent
are elements to be placed in the body element.
To achieve common style (background, page header and footer), it is
possible to define DCG non-terminals head//1 and/or body//1.
Non-terminal page//1 checks for the definition of these non-terminals in
the module it is called from as well as in the user module.
If no definition is found, it creates a head with only the HeadContent
(note that the
title is obligatory) and a body with bgcolor
set to white and the provided BodyContent.
Note that further customisation is easily achieved using html//1 directly as page//2 is (besides handling the hooks) defined as:
page(Head, Body) -->
html([ \['<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4.0//EN">\n'],
html([ head(Head),
body(bgcolor(white), Body)
])
]).
//DOCTYPE and the HTML
element. Contents is used to generate both the head and body
of the page.//
html_begin(table)
html_begin(table(border(2), align(center)))
This predicate provides an alternative to using the
\Command syntax in the html//1 specification.
The following two fragments are the same. The preferred solution depends
on your preferences as well as whether the specification is generated or
entered by the programmer.
table(Rows) -->
html(table([border(1), align(center), width('80%')],
[ \table_header,
\table_rows(Rows)
])).
% or
table(Rows) -->
html_begin(table(border(1), align(center), width('80%'))),
table_header,
table_rows,
html_end(table).
//
The non-terminal html//1 translates a specification into a list of
atoms and layout instructions. Currently the layout instructions are
terms of the format nl(N), requesting at least N
newlines. Multiple consecutive nl(1) terms are combined to
an atom containing the maximum of the requested number of newline
characters.
To simplify handing the data to a client or storing it into a file, the following predicates are available from this library:
reply_html_page(default, Head, Body).library(http_wrapper)
(CGI-style). Here is a simple typical example:
reply(Request) :-
reply_html_page(title('Welcome'),
[ h1('Welcome'),
p('Welcome to our ...')
]).
The header and footer of the page can be hooked using the
grammar-rules user:head//2 and user:body//2. The first argument passed
to these hooks is the Style argument of reply_html_page/3
and the second is the 2nd (for head//2) or 3rd (for body//2) argument of reply_html_page/3.
These hooks can be used to restyle the page, typically by embedding the
real body content in a div. E.g., the following code
provides a menu on top of each page of that is identified using the
style
myapp.
:- multifile
user:body//2.
user:body(myapp, Body) -->
html(body([ div(id(top), \application_menu),
div(id(content), Body)
])).
Redefining the head can be used to pull in scripts, but
typically html_requires//1 provides a more modular approach for pulling
scripts and CSS-files.
DOCTYPE
header,
html, head or body. It is
intended for JavaScript handlers that request a partial document and
insert that somewhere into the existing page DOM. See reply_html_page/3
to reply with a complete (valid) HTML page.Content-length
field of an HTTP reply-header.
Modern HTML commonly uses CSS and Javascript. This requires <link> elements in the HTML <head> element or <script> elements in the <body>. Unfortunately this seriously harms re-using HTML DCG rules as components as each of these components may rely on their own style sheets or JavaScript code. We added a‘mailing’system to reposition and collect fragments of HTML. This is implemented by html_post//2, html_receive//1 and html_receive//2.
//\-commands are executed by mailman/1
from print_html/1 or html_print_length/2.
These commands are called in the calling context of the html_post//2
call.
A typical usage scenario is to get required CSS links in the document head in a reusable fashion. First, we define css//1 as:
css(URL) -->
html_post(css,
link([ type('text/css'),
rel('stylesheet'),
href(URL)
])).
Next we insert the unique CSS links, in the pagehead using the following call to reply_html_page/2:
reply_html_page([ title(...),
\html_receive(css)
],
...)
////phrase(Handler, PostedTerms, HtmlTerms, Rest)
Typically, Handler collects the posted terms, creating a term suitable for html//1 and finally calls html//1.
The library predefines the receiver channel head at the
end of the
head element for all pages that write the html head
through this library. The following code can be used anywhere inside an
HTML generating rule to demand a javascript in the header:
js_script(URL) -->
html_post(head, script([ src(URL),
type('text/javascript')
], [])).
This mechanism is also exploited to add XML namespace (xmlns)
declarations to the (outer) html element using xhml_ns//2:
//xmlns
channel. Rdfa (http://www.w3.org/2006/07/SWD/RDFa/syntax/),
embedding RDF in (x)html provides a typical usage scenario where we want
to publish the required namespaces in the header. We can define:
rdf_ns(Id) -->
{ rdf_global_id(Id:'', Value) },
xhtml_ns(Id, Value).
After which we can use rdf_ns//1 as a
normal rule in html//1 to publish
namespaces from library(semweb/rdf_db). Note that this
macro only has effect if the dialect is set to xhtml. In
html mode it is silently ignored.
The required xmlns receiver is installed by html_begin//1
using the html tag and thus is present in any document that
opens the outer html environment through this library.
In some cases it is practical to extend the translations imposed by
html//1. We used this technique to define translation rules for the
output of the SWI-Prolog library(sgml) package.
The html//1 non-terminal first calls the multifile ruleset html_write:expand//1.
////<&>.//<&>".
Though not strictly necessary, the library attempts to generate reasonable layout in SGML output. It does this only by inserting newlines before and after tags. It does this on the basis of the multifile predicate html_write:layout/3
-empty,
telling the library that the element has declared empty content. In this
case the close-tag is not emitted either, but in addition html//1
interprets Arg in Tag(Arg) as a list of
attributes rather than the content.
A tag that does not appear in this table is emitted without additional layout. See also print_html/[1,2]. Please consult the library source for examples.
In the following example we will generate a table of Prolog predicates we find from the SWI-Prolog help system based on a keyword. The primary database is defined by the predicate predicate/5 We will make hyperlinks for the predicates pointing to their documentation.
:- use_module(library(http/html_write)).
:- use_module(library(pldoc/man_index)).
:- use_module(library(uri)).
html_apropos(Kwd) :-
findall(Pred, apropos_predicate(Kwd, Pred), Matches),
phrase(apropos_page(Kwd, Matches), Tokens),
print_html(Tokens).
% emit page with title, header and table of matches
apropos_page(Kwd, Matches) -->
page([ title(['Predicates for ', Kwd])
],
[ h2(align(center),
['Predicates for ', Kwd]),
table([ align(center),
border(1),
width('80%')
],
[ tr([ th('Predicate'),
th('Summary')
])
| \apropos_rows(Matches)
])
]).
% emit the rows for the body of the table.
apropos_rows([]) -->
[].
apropos_rows([pred(Name, Arity, Summary)|T]) -->
html([ tr([ td(\predref(Name/Arity)),
td(em(Summary))
])
]),
apropos_rows(T).
%! predref(Name/Arity)//
%
% Emit Name/Arity as a hyperlink to
%
% /cgi-bin/plman?name=Name&arity=Arity
predref(Name/Arity) -->
{ uri_edit([search([name=Name,arity=Arity])],
'/cgi-bin/plman', Href)
},
html(a(href(Href), [Name, /, Arity])).
% Find predicates from a keyword.
apropos_predicate(Pattern, pred(Name, Arity, Summary)) :-
man_object_property(Name/Arity, summary(Summary)),
( sub_atom_icasechk(Name, _, Pattern)
-> true
; sub_atom_icasechk(Summary, _, Pattern)
).
library(http/html_write) libraryThis library is the result of various attempts to reach at a more satisfactory and Prolog-minded way to produce HTML text from a program. We have been using Prolog for the generation of web pages in a number of projects. Just using format/2 never was not a real option, generating error-prone HTML from clumsy syntax. We started with a layer on top of format/2, keeping track of the current nesting and thus always capable of properly closing the environment.
DCG based translation however, naturally exploits Prolog's term-rewriting primitives. If generation fails for whatever reason it is easy to produce an alternative document (for example holding an error message).
In a future version we will probably define a goal_expansion/2
to do compile-time optimisation of the library. Quotation of known text
and invocation of sub-rules using the \RuleSet
and
<Module>:<RuleSet> operators are
costly operations in the analysis that can be done at compile-time.
This library is a supplement to library(http/html_write)
for producing JavaScript fragments. Its main role is to be able to call
JavaScript functions with valid arguments constructed from Prolog data.
For example, suppose you want to call a JavaScript functions to process
a list of names represented as Prolog atoms. This can be done using the
call below, while without this library you would have to be careful to
properly escape special characters.
numbers_script(Names) -->
html(script(type('text/javascript'),
[ \js_call('ProcessNumbers'(Names)
]),
The accepted arguments are described with js_expression//1.
//script element with the given
content.+
operator, which results in concatenation at the client side.
...,
js_script({|javascript(Id, Config)||
$(document).ready(function() {
$("#"+Id).tagit(Config);
});
|}),
...
The current implementation tokenizes the JavaScript input and yields syntax errors on unterminated comments, strings, etc. No further parsing is implemented, which makes it possible to produce syntactically incorrect and partial JavaScript. Future versions are likely to include a full parser, generating syntax errors.
The parser produces a term \List, which is suitable for
js_script//1 and html//1.
Embedded variables are mapped to
\js_expression(Var), while the remaining text is mapped to
atoms.
//
...
html(script(type('text/javascript'),
[ \js_call('x.y.z'(hello, 42))
]),
//['var ', Id, ' = new ', \js_call(Term)]
////nullobject(Attributes)object(Attributes), providing a more
JavaScript-like syntax. This may be useful if the object appears
literally in the source-code, but is generally less friendlyto produce
as a result from a computation.json(Term)true, false
and null, but can also be use for emitting JavaScript
symbols (i.e. function- or variable names).symbol(Atom)//
This module provides an abstract specification of HTTP server locations that is inspired on absolute_file_name/3. The specification is done by adding rules to the dynamic multifile predicate http:location/3. The speficiation is very similar to user:file_search_path/2, but takes an additional argument with options. Currently only one option is defined:
The default priority is 0. Note however that notably libraries may decide to provide a fall-back using a negative priority. We suggest -100 for such cases.
This library predefines a single location at priority -100:
http:prefix
To serve additional resource files such as CSS, JavaScript and icons,
see library(http/http_server_files).
Here is an example that binds /login to login/1.
The user can reuse this application while moving all locations using a
new rule for the admin location with the option [priority(10)].
:- multifile http:location/3.
:- dynamic http:location/3.
http:location(admin, /, []).
:- http_handler(admin(login), login, []).
login(Request) :-
...
/. Options
currently only supports the priority of the path. If http:location/3
returns multiple solutions the one with the highest priority is
selected. The default priority is 0.
This library provides a default for the abstract location
root. This defaults to the setting http:prefix or, when not
available to the path /. It is adviced to define all
locations (ultimately) relative to root. For example, use
root('home.html') rather than '/home.html'.
http://) URI
for the abstract specification Spec. Use http_absolute_location/3
to create references to locations on the same server.
This library allows for abstract declaration of available CSS and
Javascript resources and their dependencies using html_resource/2.
Based on these declarations, html generating code can declare that it
depends on specific CSS or Javascript functionality, after which this
library ensures that the proper links appear in the HTML head. The
implementation is based on mail system implemented by html_post/2
of library html_write.pl.
Declarations come in two forms. First of all http locations are
declared using the http_path.pl library. Second, html_resource/2
specifies HTML resources to be used in the head and their
dependencies. Resources are currently limited to Javascript files (.js)
and style sheets (.css). It is trivial to add support for other material
in the head. See
html_include//1.
For usage in HTML generation, there is the DCG rule html_requires//1 that demands named resources in the HTML head.
All calls to html_requires//1 for the page are collected and duplicates are removed. Next, the following steps are taken:
Use ?- debug(html(script)). to see the
requested and final set of resources. All declared resources are in html_resource/3.
The edit/1 command recognises the names of
HTML resources.
true (default false), do not include About
itself, but only its dependencies. This allows for defining an alias for
one or more resources.Registering the same About multiple times extends the properties defined for About. In particular, this allows for adding additional dependencies to a (virtual) resource.
//head using html_post/2.
The actual dependencies are computed during the HTML output phase by
html_insert_resource//1.//
//text/css and text/javascript are tried. For
example, to include a =.pl= files as a Prolog script, use:
:- multifile
html_head:mime_include//2.
html_head:mime_include(text/'x-prolog', Path) --> !,
html(script([ type('text/x-prolog'),
src(Path)
], [])).
This module provides convience predicates to include PWP (Prolog Well-formed Pages) in a Prolog web-server. It provides the following predicates:
pwp_handler / 2reply_pwp_page / 3library(http/http_dispatch). In the typical usage scenario,
one needs to define an http location and a file-search path that is used
as the root of the server. E.g., the following declarations create a
self-contained web-server for files in /web/pwp/.
user:file_search_path(pwp, '/web/pwp'). :- http_handler(root(.), pwp_handler([path_alias(pwp)]), [prefix]).
Options include:
index.pwp.true (default is false), allow for
?view=source to serve PWP file as source.permission_error(index, http_location, Location) is raised
if the handler resolves to a directory that has no index.Options supported are:
true, (default false), process the PWP file
in a module constructed from its canonical absolute path. Otherwise, the
PWP file is processed in the calling module.Initial context:
get, post, put or headWhile processing the script, the file-search-path pwp includes the current location of the script. I.e., the following will find myprolog in the same directory as where the PWP file resides.
pwp:ask="ensure_loaded(pwp(myprolog))"
Quoted from htmx.org:
htmx gives you access to AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, using attributes, so you can build modern user interfaces with the simplicity and power of hypertext
The idea behind htmx is to allow adding attributes to any HTML element that cause an HTTP request. The HTTP response is typically a (short) HTML fragment that extends or replaces an element on the page. This allows us to program a most functionality interactive seen in modern web applications using the powerful SWI-Prolog HTML generation framework rather than having to write a JSON backend and accompagnying JavaScript frontend that runs in the browser.
Below is a minimal, yet fully functional application
:- use_module(library(http/http_server)).
:- use_module(library(http/htmx)).
:- use_module(library(main)).
:- initialization(main, main).
main(_Argv) :-
http_server([port(8080)]),
thread_get_message(quit).
http:location(htmx, root(htmx), []).
:- http_handler(root(.), home, []).
home(_Request) :-
reply_html_page(
[ title('HTMX demo'),
script(src('https://unpkg.com/htmx.org'), [])
],
[ button([ 'hx-post'('/htmx/clicked'),
'hx-swap'('outerHTML')
],
'Click me')
]).
:- http_handler(htmx(clicked), reply_htmx(\clicked), []).
clicked -->
html('Thanks for clicking me!').
HTMX requires no dedicated support from the server. This library provides reply_htmx/1,2 to reply with a single HTML element rather than an entire page. Future versions of this library may provide some additional utility predicates.