Eyre

Eyre is Arvo's HTTP server module.

HTTP requests come in from clients (web frontends, mobile apps, etc.) and Eyre produces HTTP responses. Eyre has a number of ways to handle such HTTP requests which we'll briefly describe.

Authentication

Most types of HTTP request require the client to provide a valid session cookie, which is given to the client by the ship when the user logs in with their web login code. This process is documented in the Authentication section of Eyre's External API Reference.

The Channel System

An Eyre channel is a Server Sent Event (SSE) stream. It's the primary way of interacting with Urbit apps from outside Urbit, because it provides a simple JSON API that allows you to send data to apps

Eyre's "channel" system is the primary way of interacting with Urbit apps from clients outside of Urbit. It provides a simple JSON API that allows you to send data to apps, and a Server Sent Event (SSE) stream to subscribe to updates from a backend on the Urbit ship.

Detailed documentation of the channel system's JSON API is provided in Eyre's External API Reference, with corresponding examples in the Guide document.

Scrying

You can make read-only requests to Eyre with HTTP GET requests or scries. Eyre's scry interface documented in the Scry section of the External API Reference.

Threads

You can also run threads directly through Eyre via HTTP request. The API for this is not part of Eyre itself, so is documented in the seperate Threads section.

Generators

Generators (Hoon scripts) can also be used by clients via Eyre. These don't have a JSON API, but handle HTTP requests and return HTTP responses directly.

This usage is uncommon, but is explained in the %serve section of Eyre's Internal API Reference. A practical example is provided in the Generators section of the Eyre guide.

Direct HTTP Handling With Gall Agents

As well as the Channel System and Scries, it's also possible for Urbit apps to deal directly with HTTP requests using their own developer-defined logic.

This method is explained in the %connect section of Eyre's Internal API Reference document; a detailed example is provided in the Agents: Direct HTTP section of the Eyre guide.

Cross-Origin Resource Sharing (CORS)

Eyre supports both simple CORS requests and OPTIONS preflight requests. Eyre has a CORS registry with three categories: approved, rejected and requests. Eyre will respond positively for origins in its approved list, and negatively for all others. If a request comes in that isn't from an approved or rejected origin, Eyre will add that origin to the requests list. Eyre always allows all methods and headers over CORS.

This is documented in Managing CORS Origins.

Last updated