Handlers¶

Handlers

Proxy handler
Static & Single file handlers
Swindon Lattice Handler
Redirect handlers
WebsocketEcho
Empty GIF handler
Http bin handler

Proxy handler ¶

Proxy handler looks like:

example-chat-http: !Proxy
  ip-header: X-Remote-Ip
  destination: somedest/some/path

Settings:

destination¶: (required) The name of the destination and subpath where to forward request to.

ip-header¶: (default is null) Name of the HTTP header where to put source IP address to.

request-id-header¶

Deprecated, use request-id-header option in http-destination.

(default is null) Creates a request id

max-payload-size¶: (default 10MiB) Maximum payload size that might be send to this destination

stream-requests¶

(default false) If true requests bodies might be forwarded to the backend before whole body has been read.

You shouldn’t turn this option to true unless your backend is asynchronous too or can start processing request before receiving full body.

response-buffer-size¶

(default 10MiB) A high water mark of buffering responses in swindon. If this number of bytes is reached swindon will stop reading response from a backend until client receives some data.

Here are few tips for tweaking this value:

The size of most of your pages (or other content served through this proxy) should be strictly less than this value, to have good performance. This holds true even for async backends written in scripting languages.
For non-async backends even if just one page of your site doesn’t fit the buffer it might make DoS attack super-easy unless this page is protected by some rate limit.
Making this limit lower makes sense when you can generate data continuously, like fetching data from the database by chunks, or decompress data on the fly.
Consider making use cases (1-2) and (3) separate routes with different limits.

Static & Single file handlers ¶

Handler for serving static files:

robots-txt: !SingleFile
   path: /www/my-host/robots.txt
   content-type: text/plain

static-files: !Static
   path: /www/my-host/static

Common Settings ¶

pool¶: (default: default) Disk pool name to be used to serve this file.

extra-headers¶: (optional) Extra HTTP headers to be added to response.

!SingleFile settings ¶

path¶: (required) Path to file to serve.

content-type¶: (optional) Set Content type for served file. By default mime type is guessed by extension

!Static Settings ¶

path¶: (required) Path to directory to serve.

mode¶

(default: relative_to_route) Sets path resolve mode:

relative_to_domain_root

Use whole URL path as filesystem path to file;
relative_to_route

Use only route suffix/tail as filesystem path to file;
with_hostname

Add hostname as the first directory component

These pathes, ofcourse, relative to path setting.

text-charset¶: (optional, default utf-8) Sets charset parameter of Content-Type header.

strip-host-suffix¶: (optional) If mode is with_hostname strip the specified suffix from the host name before using it as a first component of a directory. For example, if strip-host-suffix is example.org then URL http://something.example.com/xx/yy will be searched in the directory something/xx/yy.

index-files¶

(default []) List of files to be used as a directory index. If none of them found (or index-files is an empty list) the 403 error is returned.

MIME type for index file is guessed just like for any other file.

Example:

index-files: ["index.html", "index.htm"]

generate-index¶: (default false) Generate HTML file with list of files if no index-files are present.

Note

We don’t guarantee format of that HTML file just yet, it may change in future.

generated-index-max-files¶: (default 100000) Maximum number of files to show in generated index. This is required to prevent DoS attacks on listing large directories.

!VersionedStatic Settings ¶

VersionedStatic is a handler that returns file by revision specified in query args. For example url /img/myimage.jpg?r=deadbeef is served from /versioned-root/de/adbeef/myimage.jpg.

These files are considered to be immutable, i.e. if file changes the version changes. So we send files with headers:

Cache-Control: public, max-age=31536000, immutable

‥ and Expires in 365 days in the future (for old user agents, also date more than 1 year might not work).

In case we the target version is missing and we have fallback enabled (see below), we serve them uncacheable:

Cache-Control: no-cache, no-store, must-revalidate
Expires: 0

And for files which doesn’t have revision specified at all and no-version (or less strict option) specified in fallback-to-plain we we serve files without Cache-Control header at all (usually cached for user’s session).

We may add more settings to customize cache headers in future.

versioned-root¶

(required) Root of the directory where versioned files should be served from. Basic pattern how files are served from there is:

<versioned-root>/xx/yyyyyy/filename.ext

In particular:

xx/yyyyy is a value extracted from version-arg
Name of the file is original one, but without path. Name is kept barely to debug issues easier.
Extension (suffix) of the filename is kept as is to be able to find out mime type.

So for example url /img/myimage.jpg?r=deadbeef is served from /versioned-root/de/adbeef/myimage.jpg.

plain-root¶

(optional) When no file found in versioned-root we may search in plain-root by original filename/path depending on fallback-to-plain setting. This works in a way similar to Static.

It’s expected that plain-root contains files of the latest version of an application. And it’s main purpose is to serve well-known files like robots.txt or crossdomain.xml.

version-arg¶: (required) The query argument to get version from. It’s usually some short thing like r, v, ver, revision, hash.

version-split¶

(required) Parts to split version argument into, to search for a path. Sum of all number here must be equal to the length of the version argument, we do not support variable length yet.

For example version-split: [2, 6] means that value must consist of eight characters and that myimage.gif?r=deadbeef is searched in de/adbeef folder.

version-chars¶: (required) Validates version chars allowed in hash string. Currently only lowercase-hex mode is supported.

fallback-to-plain¶: (default never) When to fallback to serving files from plain-root. We have a very conservative default, it’s useful for staging servers where you want specifically, For production deployment, you may wish to change it to more lenient ones.

fallback-mode¶: (default relative_to_route) A mode to serve url if there is no versioned file. This directly corresponds to mode of !Static.

text-charset¶: (optional, default utf-8) Sets charset parameter of Content-Type header.

Swindon Lattice Handler ¶

Swindon lattice handler:

example-chat: !SwindonLattice
   session-pool: example-chat-session
   http-route: backend/fallback
   message-handlers:
     "*": backend/path

Changed in version v0.7.0: Old name of the handler type is SwindonChat which is removed in v0.7.0.

The backend/path here, i.e. the message handler, should have override-host-header setting set, so that swindon knows what Host header to send for RPC requests.

Settings:

session-pool¶: (required) Sets session pool to be used with this chat

http-route¶: (optional) Sets fallback http route to be used in case when URL is accessed with plain http request, not websocket upgrade request.

message-handlers¶

(required) Mapping of chat method name patterns to http handlers.

Allowed patterns of 3 types:

"*" – (required) special “default” pattern; any method with doesn’t match

any other pattern will be sent to this http handler.

"prefix.*" – “glob” pattern matches method name by prefix including dot,

for instance, pattern "chat.*" will match:

chat.send_message
chat.hello

but will not match:

chat_send_message
chat

also “chat.send*” is invalid pattern, it will be read as ‘exact’ pattern, however will not work ever because “*” is not allowed in method names.

"exact.pattern" – “exact” pattern, matches whole method name.

Patterns match order is: “exact” then “glob” otherwise “default”.

compatibility¶

(default no value, i.e. latest) This allows to enable old behavior of the protocol. Here are the list of compatibility breaks:

v0.5.4 – allows skipping Sec-WebSocket-Protocol
v0.6.2 – does three things:
- uses /tangle/authorize_connection and /tangle/session_inactive instead of /swindon//-prefixed ones
- uses Authorization: Tangle <base64-encoded-data>
- treats arbitrary Content-Type as application/json rather than verifying it

Note: some behavior is not restored intentionally, in particlar:

Both swindon.* and tangle.* methods are reserved
Lattices swindon.* are reserved too
_register CRDT’s and presence API work anyway

Redirect handlers ¶

!BaseRedirect handler is used for permanent base host redirects:

routing:
   example.com: new-handler
   example.org: redirect
handlers:
   redirect: !BaseRedirect
      redirect-to-domain: example.com

   new-handler: !Proxy
      destination: somedest/

redirect-to-domain¶: Destination domain to redirect to.

!StripWWWRedirect handler is used redirect to URL without www. prefix:

routing:
   example.com: new-handler
   www.example.com: strip-www
handlers:
   strip-www: !StripWWWRedirect
   example.com: !Proxy
      destination: somedest/

Note

Both redirects use 301 Moved Permanently status code.

WebsocketEcho ¶

Handler for a dummy websocket echo service:

echo: !WebsocketEcho

Empty GIF handler ¶

Empty GIF handler is used to serve static empty pixel gif image:

empty-gif: !EmptyGif

Seetings:

extra-headers¶: Mapping of extra http headers to return in response.

Http bin handler ¶

Serves kind’a request-response testing service, see http://httpbin.org.