Edit

Eyre Data Types

This document describes the data types used by Eyre as defined in /sys/lull.hoon. It's separated into two sections:

Eyre - Eyre-specific data types.

HTTP - HTTP data types shared between Eyre and Iris.

Eyre

$cache-entry

+$  cache-entry
  $:  auth=?
  $=  body
  $%  [%payload =simple-payload:http]
  ==  ==

  • .auth: Whether the request must include a valid session cookie or otherwise be authenticated. If this is false, the entry will be publicly accessible.

  • .body: The HTTP response to give. This contains a [%payload =simple-payload:http]. See the $simple-payload:http for more details of the data.

$origin

+$  origin  @torigin

A single CORS origin as used in an HTTP Origin header and the $cors-registry.

$cors-registry

CORS origins categorised by approval status. The requests +set contains all $origins Eyre has received in the headers of HTTP requests that have not been explicitly approved or rejected. The approved and rejected +sets are those that have been explicitly approved or rejected.

$outstanding-connection

An HTTP connection that is currently open. The $action is how it's being handled (e.g. by a Gall app, the channel system, etc). The $inbound-request is the original request which opened the connection. The $response-header contains the status code and headers. The .bytes-sent is the total bytes sent so far in response.

$authentication-state

This represents the authentication state of all sessions. It maps session cookies (without the urbauth-{SHIP}= prefix) to $sessions.

$session

This represents server-side data about a session. The .expiry-time is when the $session expires and .channels is the +set of $channel names opened by the session.

$channel-state

The state used by the channel system. The $session is a +map between channel names and $channels and the .duct-to-key +maps $ducts to $channel names.

$timer

A reference to a timer so it can be cancelled or updated. The $date is when it will fire and the $duct is what set the timer.

$channel-event

An unacknowledged event in the channel system.

$channel

This is the state of a particular channel in the channel system.

  • .mode says whether the channel sends/received JSON or nouns.

  • .state is either the expiration time or the duct currently listening.

  • .next-id is the next event ID to be used in the event stream.

  • .last-ack is the date of the last client ack and is used for clog calculations in combination with .unacked.

  • .events queue contains all unacked events:

    • .id is the server-set event ID.

    • .request-id is the client-set request ID.

    • .channel-event is the event itself.

  • .unacked +map contains the unacked event count per .request-id and is used for clog calculations.

  • .subscriptions +map contains gall subscriptions by .request-id.

  • .heartbeat is the SSE heartbeat $timer.

$binding

A $binding is a rule to match a URL $path and optional .site domain which can then be tied to an $action. A $path of /foo will also match /foo/bar, /foo/bar/baz, etc. If the .site is ~ it will be determined implicitly. A binding must be unique.

$action

The action to take when a $binding matches an incoming HTTP request.

$generator

This refers to a generator on a local ship that can handle requests. Note that serving generators via Eyre is not fully implmented and should not be used.

$http-config

The configuration of the runtime HTTP server itself. The secure field contains the PEM-encoded RSA private key and certificate or certificate chain when using HTTPS, and otherwise is ~ when using plain HTTP. The proxy field is not currently used. The log field turns on HTTP(S) access logs but is not currently implemented. The redirect field turns on 301 redirects to upgrade HTTP to HTTPS if the key and cert are set in secure.

$http-rule

This is for updating the server configuration. In the case of %cert, a cert of ~ clears the HTTPS cert & key, otherwise cert contains the PEM-encoded RSA private key and certificate or certificate chain. In the case of %turf, a %put .action sets a domain name and a %del .action removes it. The $turf contains the domain name.

$address

A client IP address.

$inbound-request

An inbound HTTP request and metadata. The authenticated field says whether the request was made with a valid session cookie. The secure field says whether it was made with HTTPS. The $address is the IP address from which the request originated, except if it came from localhost and included a Forwarded header, in which case it's the address specified in that header. The $request:http contains the HTTP request itself.

HTTP

$header-list:http

An ordered list of HTTP headers. The key is the header name e.g 'Content-Type' and the value is the value e.g. text/html.

$method:http

An HTTP method.

$request:http

A single HTTP request. The $method:http is the HTTP method, the url is the unescaped URL, the $header-list:http contains the HTTP headers of the request and the body is the actual data. An $octs is just [p=@ud q=@] where .p is the byte-length of .q, the data.

$response-header:http

The status code and $header-list:http of an HTTP response.

$http-event:http

Packetized HTTP.

Urbit treats Earth's HTTP servers as pipes, where Urbit sends or receives one or more $http-events. The first of these will be a %start, and the last will always be %cancel or will have complete set to %.y to finish the connection.

Calculation of control headers such as 'Content-Length' or 'Transfer-Encoding' should be performed at a higher level; this structure is merely for what gets sent to or received from Earth.

$simple-payload:http

A simple, one-event response used for generators. The $reponse-header:http contains the status code and HTTP headers. The $octs in the $data contains the body of the response and is a [p=@ud q=@] where .p is the byte-length of .q, the data.

PreviousEAuthNextEyre External API

Last updated