# 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 <a href="#authentication" id="authentication"></a>

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](https://docs.urbit.org/urbit-os/kernel/external-api-ref#authentication) section of Eyre's [External API Reference](https://docs.urbit.org/urbit-os/kernel/eyre/external-api-ref).

## The Channel System <a href="#the-channel-system" id="the-channel-system"></a>

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](https://html.spec.whatwg.org/#server-sent-events) (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](https://docs.urbit.org/urbit-os/kernel/eyre/external-api-ref), with corresponding examples in the [Guide](https://docs.urbit.org/urbit-os/kernel/guide#using-channels) document.

## Scrying <a href="#scrying" id="scrying"></a>

You can make read-only requests to Eyre with HTTP GET requests or scries. Eyre's scry interface documented in the [Scry](https://docs.urbit.org/urbit-os/kernel/external-api-ref#scry) section of the [External API Reference](https://docs.urbit.org/urbit-os/kernel/eyre/external-api-ref).

## Threads <a href="#threads" id="threads"></a>

You can also run threads directly through Eyre via HTTP request. The [API for this](https://docs.urbit.org/urbit-os/base/threads/http-api) is not part of Eyre itself, so is documented in the seperate [Threads](https://docs.urbit.org/urbit-os/base/threads) section.

## Generators <a href="#generators" id="generators"></a>

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`](https://docs.urbit.org/urbit-os/kernel/tasks#serve) section of Eyre's [Internal API Reference](https://docs.urbit.org/urbit-os/kernel/eyre/tasks). A practical example is provided in the [Generators](https://docs.urbit.org/urbit-os/kernel/guide#generators) section of the Eyre [guide](https://docs.urbit.org/urbit-os/kernel/eyre/guide).

## Direct HTTP Handling With Gall Agents <a href="#direct-http-handling-with-gall-agents" id="direct-http-handling-with-gall-agents"></a>

As well as the [Channel System](#the-channel-system) and [Scries](#scrying), 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`](https://docs.urbit.org/urbit-os/kernel/tasks#connect) section of Eyre's [Internal API Reference](https://docs.urbit.org/urbit-os/kernel/eyre/tasks) document; a detailed example is provided in the [Agents: Direct HTTP](https://docs.urbit.org/urbit-os/kernel/guide#agents-direct-http) section of the Eyre [guide](https://docs.urbit.org/urbit-os/kernel/eyre/guide).

## Cross-Origin Resource Sharing (CORS) <a href="#cross-origin-resource-sharing" id="cross-origin-resource-sharing"></a>

Eyre supports both simple [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://docs.urbit.org/urbit-os/kernel/guide#managing-cors-origins).