# Elide global

> The `Elide` global: version and build metadata, `Elide.serve()` options and defaults (bind address, port, TLS, body limits, timeouts), and serving a module's default-exported fetch handler.

`Elide` is a global with build metadata and the `serve()` HTTP entry point.

| Property | Type |
|---|---|
| `version` | `string` |
| `debug` | `boolean` |
| `release` | `boolean` |
| `buildMode` | `string` |
| `targetArchitecture` | `string` |

## `Elide.serve(options)`

`Elide.serve` takes a Fetch-style handler and returns an object with `port`, `hostname`, and `close()`:

```js
const server = Elide.serve({
  port: 3000,
  hostname: "127.0.0.1",
  fetch(request) {
    return new Response("hello");
  },
});
```

| Option | Default | Effect |
|---|---|---|
| `fetch` | required | Handler: receives a `Request`, returns a `Response` or a Promise of one. |
| `hostname` | all interfaces (`0.0.0.0`) | Interface to bind. |
| `port` | `0` | TCP port; `0` picks a free port, read it from `server.port`. |
| `cert`, `key` | none | PEM certificate and private key; with both set the server speaks HTTPS. |
| `idleTimeoutMs` | `30000` | Time allowed to read a request body; a stalled body gets `408`. `0` disables it. |
| `maxBodyBytes` | `104857600` (100 MiB) | Larger request bodies get `413 Payload Too Large`. `0` removes the cap. |

Without `hostname`, the server listens on every network interface and is reachable from other machines. Pass
`hostname: "127.0.0.1"` to accept local connections only:

```js
const open = Elide.serve({ fetch: () => new Response("ok") });
console.log(open.hostname, open.port);
open.close();

const local = Elide.serve({ hostname: "127.0.0.1", fetch: () => new Response("ok") });
console.log(local.hostname, local.port);
local.close();
```

```terminaloutput
0.0.0.0 36518
127.0.0.1 38424
```

- `elide run` does not exit until `close()` is called.
- Connections are accepted once the entry module, including top-level `await`, has finished. A request made from
  top-level code to the module's own server waits forever; make it from a callback such as `setTimeout`.
- It serves HTTP/1.1, and HTTP/2 over TLS.
- Request and response bodies stream; return a `Response` backed by a `ReadableStream` to stream output.
- `request.signal` aborts when the client disconnects.
- Responses are sent as returned and never recompressed; set `Content-Encoding` and `Vary: Accept-Encoding` yourself.

### HTTPS

```js
import { readFileSync } from "node:fs";

const server = Elide.serve({
  hostname: "127.0.0.1",
  port: 8443,
  cert: readFileSync("cert.pem", "utf8"),
  key: readFileSync("key.pem", "utf8"),
  fetch: (request) => new Response(`hello over ${new URL(request.url).protocol}\n`),
});
```

```bash
curl -sk https://127.0.0.1:8443/
```

```terminaloutput
hello over https:
```

### Request limits

```js
const server = Elide.serve({
  hostname: "127.0.0.1",
  port: 0,
  maxBodyBytes: 1024,
  async fetch(request) {
    const body = await request.text();
    return new Response(`received ${body.length} bytes\n`);
  },
});

setTimeout(async () => {
  for (const size of [512, 4096]) {
    const res = await fetch(`http://127.0.0.1:${server.port}/`, { method: "POST", body: "x".repeat(size) });
    console.log(size, res.status, (await res.text()).trim());
  }
  server.close();
}, 0);
```

```terminaloutput
512 200 received 512 bytes
4096 413 Payload Too Large
```

## Exported fetch handler

An entry ES module can default-export an object with a `fetch(request)` method instead:

```js
export default {
  hostname: "127.0.0.1",
  port: 3000,
  fetch(request) {
    return new Response(new URL(request.url).pathname);
  },
};
```

- `elide run`, `elide serve`, and `elide dev` start it after the module, including top-level `await`, finishes.
- Imported modules never start a server.
- `fetch` is called with the exported object as `this` and returns a `Response` or a Promise of one.
- `run` binds the exported `hostname` and `port`, default `127.0.0.1:8080`; `--host` and `--port` override them in
  `serve` and `dev`.

## Samples

- [Server-sent events](https://elide.help/docs/code-samples#server-sent-events)
- [Request limits](https://elide.help/docs/code-samples#request-limits)
- [Multi-context server](https://elide.help/docs/code-samples#multi-context-server)