# Runtime globals

Maligator 0.1.0-alpha.27 · Experimental
Source revision: 96c331078104a0c9275238dbd0a714f5c48a53b6
Canonical: https://maligator.ddv.tools/api/runtime

The lowercase `mal` namespace exposes captured assets. The uppercase `Mal` namespace exposes the Web host extension. Their declarations are always available after loading the package types; the build configuration controls runtime availability.

<a id="mal"></a>

## mal

Requires `surface.maligator` (enabled by default). Configure named assets before calling `mal.assets.materialize`. Unknown names, invalid options, and filesystem failures throw synchronously. Completed snapshots are reused by content identity; the returned path is absolute. See [Embed files](/guides/assets) for a complete file/directory example.

<a id="Mal"></a>

## Mal

Requires `surface.webPlatform` (disabled by default). `Mal.serve` starts an HTTP listener and returns its bound port. The API is experimental: the handle has no public shutdown method, and invalid handlers or bind failures are not yet consistently reported as exceptions. Use valid options and verify startup before accepting traffic.


```typescript http.ts
import { ready } from "maligator:application";

const server = Mal.serve({
	hostname: "127.0.0.1",
	port: 3000,
	fetch(request) {
		if (new URL(request.url).pathname === "/") {
			return new Response("hello", { headers: { "content-type": "text/plain" } });
		}
		return new Response("Not found", { status: 404 });
	},
});
console.log(`Listening on http://127.0.0.1:${server.port}`);
ready();
```


Run this as `src/index.ts` with `surface.webPlatform: true`; `curl http://127.0.0.1:3000/` returns `hello`. See [Serve HTTP](/guides/http) for the config and Node alternative.

<a id="MaligatorMaterializeOptions"></a>

## MaligatorMaterializeOptions


<details><summary>Full TypeScript declaration</summary>


```typescript
export interface MaligatorMaterializeOptions {
	/** Parent directory for the content-addressed materialization. Defaults to the OS temporary directory. */
	baseDirectory?: string;
}
```

</details>


<a id="MaligatorMaterializeOptions.baseDirectory"></a>

### MaligatorMaterializeOptions.baseDirectory

Parent directory for the content-addressed materialization. Defaults to the OS temporary directory.

```typescript
baseDirectory?: string;
```


<a id="MaligatorAssets"></a>

## MaligatorAssets


<details><summary>Full TypeScript declaration</summary>


```typescript
export interface MaligatorAssets {
	/**
	 * Atomically write a named snapshot and return its absolute file/directory path.
	 * Completed materializations are reused by content identity. Unknown names,
	 * invalid options, and filesystem failures throw synchronously.
	 * @see https://maligator.ddv.tools/api/runtime#mal.assets.materialize
	 */
	materialize(name: string, options?: MaligatorMaterializeOptions): string;
}
```

Types: [`MaligatorMaterializeOptions`](/api/runtime#MaligatorMaterializeOptions)


</details>


<a id="mal.assets.materialize"></a>

### mal.assets.materialize

Atomically write a named snapshot and return its absolute file/directory path.
Completed materializations are reused by content identity. Unknown names,
invalid options, and filesystem failures throw synchronously.

```typescript
materialize(name: string, options?: MaligatorMaterializeOptions): string;
```

Types: [`MaligatorMaterializeOptions`](/api/runtime#MaligatorMaterializeOptions)



<a id="MaligatorRuntime"></a>

## MaligatorRuntime


<details><summary>Full TypeScript declaration</summary>


```typescript
export interface MaligatorRuntime {
	readonly assets: MaligatorAssets;
}
```

Types: [`MaligatorAssets`](/api/runtime#MaligatorAssets)


</details>


<a id="MaligatorRuntime.assets"></a>

### MaligatorRuntime.assets



```typescript
readonly assets: MaligatorAssets;
```

Types: [`MaligatorAssets`](/api/runtime#MaligatorAssets)



<a id="MaligatorServeOptions"></a>

## MaligatorServeOptions


<details><summary>Full TypeScript declaration</summary>


```typescript
export interface MaligatorServeOptions {
	/** Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener. */
	hostname?: string;
	/** TCP port, 0 through 65535. Defaults to 0, which asks the OS to choose a port. */
	port?: number;
	/** Handle a request with a Response or an awaited response. */
	fetch(request: Request): Response | PromiseLike<Response>;
	/** Header deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
	 * @default 60000 */
	headersTimeout?: number;
	/** Request deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
	 * @default 300000 */
	requestTimeout?: number;
	/** Idle keep-alive deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
	 * @default 5000 */
	keepAliveTimeout?: number;
	/** Concurrent connection limit; 0 also selects the default. Integer 0..2147483647.
	 * @default 1024 */
	maxConnections?: number;
}
```

</details>


<a id="MaligatorServeOptions.hostname"></a>

### MaligatorServeOptions.hostname

Bind address. Defaults to 0.0.0.0; use 127.0.0.1 for a local-only listener.

```typescript
hostname?: string;
```


<a id="MaligatorServeOptions.port"></a>

### MaligatorServeOptions.port

TCP port, 0 through 65535. Defaults to 0, which asks the OS to choose a port.

```typescript
port?: number;
```


<a id="MaligatorServeOptions.fetch"></a>

### MaligatorServeOptions.fetch

Handle a request with a Response or an awaited response.

```typescript
fetch(request: Request): Response | PromiseLike<Response>;
```


<a id="MaligatorServeOptions.headersTimeout"></a>

### MaligatorServeOptions.headersTimeout

Header deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
Default: `60000`.

```typescript
headersTimeout?: number;
```


<a id="MaligatorServeOptions.requestTimeout"></a>

### MaligatorServeOptions.requestTimeout

Request deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
Default: `300000`.

```typescript
requestTimeout?: number;
```


<a id="MaligatorServeOptions.keepAliveTimeout"></a>

### MaligatorServeOptions.keepAliveTimeout

Idle keep-alive deadline in milliseconds; 0 also selects the default. Integer 0..2147483647.
Default: `5000`.

```typescript
keepAliveTimeout?: number;
```


<a id="MaligatorServeOptions.maxConnections"></a>

### MaligatorServeOptions.maxConnections

Concurrent connection limit; 0 also selects the default. Integer 0..2147483647.
Default: `1024`.

```typescript
maxConnections?: number;
```


<a id="MaligatorServer"></a>

## MaligatorServer


<details><summary>Full TypeScript declaration</summary>


```typescript
export interface MaligatorServer {
	/** Actual bound port, including an OS-selected port when the requested port was 0. */
	readonly port: number;
}
```

</details>


<a id="MaligatorServer.port"></a>

### MaligatorServer.port

Actual bound port, including an OS-selected port when the requested port was 0.

```typescript
readonly port: number;
```


<a id="MaligatorWebRuntime"></a>

## MaligatorWebRuntime


<details><summary>Full TypeScript declaration</summary>


```typescript
export interface MaligatorWebRuntime {
	/**
	 * Start an HTTP listener. Requires surface.webPlatform. The current handle exposes
	 * its bound port; it has no public stop method. Invalid timeout/connection limits throw.
	 * @see https://maligator.ddv.tools/api/runtime#Mal.serve
	 */
	serve(options: MaligatorServeOptions): MaligatorServer;
}
```

Types: [`MaligatorServeOptions`](/api/runtime#MaligatorServeOptions), [`MaligatorServer`](/api/runtime#MaligatorServer)


</details>


<a id="Mal.serve"></a>

### Mal.serve

Start an HTTP listener. Requires surface.webPlatform. The current handle exposes
its bound port; it has no public stop method. Invalid timeout/connection limits throw.

```typescript
serve(options: MaligatorServeOptions): MaligatorServer;
```

Types: [`MaligatorServeOptions`](/api/runtime#MaligatorServeOptions), [`MaligatorServer`](/api/runtime#MaligatorServer)