1
0
Fork 0
liza/doc/server.texi

303 lines
10 KiB
Plaintext
Raw Normal View History

@c This document is part of the Liza Data Collection Framework manual.
@c Copyright (C) 2017 R-T Specialty, LLC.
@c
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c Texts. A copy of the license is included in the section entitled ``GNU
@c Free Documentation License''.
@node Server
@chapter Liza Server
@maintenance{The @srcrefjs{server/daemon,Daemon} monolith and
@srcrefjs{server,Server},
among other things,
need refactoring.
Quote initialization code should be moved into
@srcrefjs{server,ProgramInit}.}
@helpwanted{}
@cindex Server
The @dfn{server}@footnote{
@cindex Quote Server
Which may also be referenced as ``quote server'' in certain legacy
contexts,
referring to Liza's origin as an insurance rating system.}
is a RESTful service that serves as the HTTP server.
It is designed to run under Node.js,
motivated by the benefits of sharing code with the@tie{}Client
(@pxref{Client}).
The daemon is handled by the abstract @srcrefjs{server/daemon,Daemon}
monolith,
which requires that a concrete @code{#getEncryptionService}
method be defined by a subtype or trait.
An example script to start the server is shown in @ref{f:server-start}.
@cindex Encryption Service
@tip{For local development,
or to avoid use of any encryption service,
use @srcrefjs{server/daemon,DevDaemon},
which uses a dummy encryption service.}
To start the server,
invoke @srcref{bin/server}.
You may also invoke @srcref{bin/server.js} directly using Node.js,
but the use of @srcref{bin/server} is recommended,
as it uses the Node.js executable determined at configure-time,
along with any command-line options required for Liza@tie{}Server
to function correctly.
Additional options can be provided to Node.js using the
@var{NODE_FLAGS} environment variable,
which will be @emph{appended} to the configure-time flags.
This environment variable is @emph{not} escaped or quoted,
so be mindful of word expansion.
@float Figure, f:server-start
@example
$ bin/server -c path/to/config.json
# providing additional options to node
$ NODE_FLAGS=--debug bin/server -c path/to/config.json
@end example
@caption{Starting the Liza Server}
@end float
@cindex HTTP Server
The HTTP server is managed by
@srcrefjs{server/daemon,http_server}.
@menu
* Configuration:Server Configuration. Server configuration.
* Requests:: Handling HTTP requests.
* Posting Data:: Handling step saves and other posts.
* Server-Side Data API Calls:: Accessing external resources on the server.
* Encryption Service:: Managing sensitive data.
@end menu
@node Server Configuration
@section Configuration
@helpwanted{}
@cindex Configuration
Liza is migrating to actual configuration file in place of environment
variables.
If no configuration is explicitly specified,
it uses @srcrefraw{conf/vanilla-server.json}.
Configuration loading is handled by @srcrefjs{conf,ConfLoader}.
The configuration store @srcrefjs{conf,ConfStore} is asyncrhonous,
so loading configuration from any external system is supported.@footnote{
Provided that you write the code to load from that system,
that is.}
@node Requests
@section HTTP Requests
@helpwanted{}
@cindex Session
@cindex PHPSESSID
@cindex Memcache
Each HTTP request produces a @srcrefjs{server/request,UserRequest}
associated with a @srcrefjs{server/request,UserSession}.
Sessions are tightly coupled with PHP@footnote{
They don't have to be@mdash{}refactoring is needed.};
an existing PHP session is expected,
as identified by the @samp{PHPSESSID} cookie.
Sessions are shared via Memcache
(see @srcrefjs{server/cache,ResilientMemcache}).@footnote{
Via a @url{https://secure.php.net/manual/en/memcached.sessions.php,memcache session handler}.}
If a session is not found (or is invalid),
an HTTP@tie{}@code{500} status code is returned and the
HTTP@tie{}request is aborted.
@cindex Timeout
@cindex Request timeout
Requests are subject to a 120@tie{}second timeout,
after which the request will be served an HTTP@tie{}@code{408}
status code.
Note that this @emph{does not stop background processing}@mdash{
}this timeout exists to prevent the user from hanging indefinitely.
@cindex Long-running requests
@tip{If a process intends to perform background processing for any length
of time (longer than a few seconds),
it should complete the request as quickly as possible and
use some other mechanism to report back progress
(e.g. polling).}
The @srcrefjs{server/request,UserRequest} exposes raw request data with
minor processing.
@table @strong
@item Path (@jsmethod{getUri})
The path component of the URI. The method name is unfortunate.
@item Query data (@jsmethod{getGetData})
Query string processed into a key/value object.
Despite the name,
this is also populated if non-GET requests contain query strings.
@item POST data (@jsmethod{getPostData})
POST data processed into an object as if it were a query string
(just as @jsmethod{getGetData}).
Since this requires data that is streamed asynchronously,
this method takes a callback that waits for all data to become
available;
if the data are already available,
it is immediately invoked with the processed POST data.
@item Cookies (@jsmethod{getCookies})
Cookies parsed into a key/value object.
@item Remote address (@jsmethod{getRemoteAddr})
IP address of the origin of the request.
If the server is behind a proxy that sets the
@samp{X-Forwarded-For} header,
it is used instead.
@item Host address (@jsmethod{getHostAddr})
Hostname of the server.
If the server is behind a proxy that sets the
@samp{X-Forwarded-Host} header,
it is used instead.
@item Origin (@jsmethod{getOrigin})
Origin of request.
Only available if at lease one of the @samp{Origin} or
@samp{Referer} headers are set.
This is useful mainly for determining the protocol and host while
behind a proxy.
@item User agent (@jsmethod{getUserAgent})
The user agent string of the request.
@item Session ID (@jsmethod{getSessionId})
The user's unique session id (@samp{PHPSESSID}).
@item Session ID name (@jsmethod{getSessionIdName})
The name of the cookie from which the session ID originated
(hard-coded to @samp{PHPSESSID}).
@end table
@todo{Document return format and writing response data.}
@node Posting Data
@section Posting Data
@cindex Post
@cindex Bucket diff
@cindex Step save
A diff of the bucket data (@pxref{Bucket Diff}) is posted to the
server on step@tie{}save.
This operation is performed asynchronously@mdash{
}the client need not wait for the step to save before the next can
be requested.
Since validations are shared between the server and the client
(@pxref{Validation}),
saving should only fail in exception situations.
Should a failure occur,
the server will instruct the client to kick the user back to the
previous step (@dfn{kickback}).
A step cannot be saved if it is locked;
such attempts will result in an error.
To prevent a user from skipping steps,
the client may post only one step past the last step that has
successfully saved;
otherwise, the user is kicked back to the last step that was saved.
Once those basic checks have passed,
the document is updated:
@enumerate
@item
@cindex Data sanitization
The diff is first @dfn{sanitized} to strip out unknown fields,
internal fields posted by non-internal users,
and to filter fields on permitted characters;
@item
The sanitized diff is then applied to the existing bucket on the
document;
@item
@cindex Calculated values, server-side
Calculated values marked for storage (@pxref{Calculated Values}) are
re-calculated on the server (the values posted by the client have
already been discarded by the first step in this list);
@item
Server-side @dapi{} calls (@pxref{Data API}) are triggered using the
diff as input data and an empty bucket for response storage
(@pxref{Server-Side Data API Calls});
@item
@cindex Premium calculation date
The last premium calculation date is cleared (indicating that
premiums are no longer valid);@footnote{
This concept is tightly coupled with insurance;
it should be factored out at some point.}
@item
@cindex Encryption
Data marked as sensitive is encrypted and the ciphertext written to
the bucket in place of the plaintext (@pxref{Encryption Service});
@item
@cindex Top visited step
The current step is incremented and the @dfn{top visited
step}@tie{} is set to the larger of the incremented step or the
existing top visited step id; and then
@item
The new document state and bucket data are written to the database.
@end enumerate
@node Server-Side Data API Calls
@section Server-Side Data API Calls
@maintenance{This makes use of @srcrefjs{server/meta,DapiMetaSource}
to encapsulate the horrible API of @srcrefjs{dapi,DataApiManager};
the latter needs cleanup to remove the former.}
@cindex Data API
@cindex Document metadata
Server-side @dapi{} calls (@pxref{Data API}) are triggered on
step save (@pxref{Posting Data}) and are handled much like they are
on the client.
Such calls are made automatically only for document metadata.
Results of sever-side calls are @emph{not} written to the bucket
and are therefore useful for data that the client should not be
permitted to modify;
it also allows data to be kept secret from the client.@footnote{
All bucket data is served to the client,
with the exception of internal fields if the user is non-internal.}
@dapi{} results on the client can be mapped back to multiple bucket values;
the server, however, has serious concerns with how data are
propagated for data integrity and security reasons.
Further,
document metadata can be structured,
unlike the Bucket which has a rigid matrix format (@pxref{Bucket}).
Therefore,
the entire response is mapped into the parent field;
defined return values are used only for filtering.
@node Encryption Service
@section Encryption Service
@helpwanted