Class: Server<US>

Defined in: net/server/server.ts:331

A simple abstraction around an HTTP server. The server is built using two primitives: endpoints and middlewares.

The generic parameter US defines the schema of User items throughout the system. Pass your custom user schema to enable type-safe user management and authorization. See @sessions.md and @authorization-rules.md for details on user authentication and access control.

Usage Examples

1. Standalone Server

import { Server } from './net/server/server.ts';

const server = new Server({
  // ...options
});

await server.start();
// The server now listens for HTTP requests on the default port (8080).

2. Integrating into an Existing Server

If you want to use GoatDB's server as a handler within another HTTP server, you can call await server.processRequest(request, info) directly:

import { Server } from './net/server/server.ts';

const server = new Server({
  // ...options
});

// Inside your own HTTP server handler:
async function handler(request: Request) {
  const info = { // ...ServeHandlerInfo... };
  return await server.processRequest(request, info);
}

// Use `handler` in your custom server framework.

Endpoints:

Endpoints are the core request handlers that process specific HTTP requests. Each endpoint has a filter that determines which requests it handles, and a processRequest method that generates the response. Endpoints are executed in registration order until the first matching endpoint is found.

Middlewares:

Middlewares provide cross-cutting functionality that runs before and/or after endpoint processing. They can:

• Block requests before they reach endpoints (e.g. for authentication)
• Modify responses after endpoints complete (e.g. adding headers)
• Log requests and responses
• Handle errors

All registered middlewares run for each request in registration order.

Type Parameters

Type Parameter
US extends Schema

Constructors

Constructor

new Server<US>(options): Server<US>

Defined in: net/server/server.ts:346

Parameters

Parameter	Type
options	ServerOptions<US>

Returns

Server<US>

Accessors

address

Get Signature

get address(): object

Defined in: net/server/server.ts:684

Get the full server address including dynamically allocated port. Returns undefined if server hasn't started yet.

Returns

object

hostname

hostname: string

port

port: number

---

port

Get Signature

get port(): number

Defined in: net/server/server.ts:676

Get the actual port the server is listening on. This is useful when port 0 was specified for dynamic allocation. Returns undefined if server hasn't started yet.

Returns

number

Methods

orgIds()

orgIds(): Iterable<string>

Defined in: net/server/server.ts:499

Returns an iterable of all organization IDs that have services initialized.

Returns

Iterable<string>

An iterable of organization ID strings

---

processRequest()

processRequest(goatReq, info): Promise<Response>

Defined in: net/server/server.ts:527

Processes an incoming HTTP request through the server's middleware and endpoint pipeline.

Parameters

Parameter	Type	Description
goatReq	GoatRequest	The incoming HTTP request
info	ServeHandlerInfo	Additional request information

Returns

Promise<Response>

Promise resolving to the HTTP response

---

registerEndpoint()

registerEndpoint(ep): void

Defined in: net/server/server.ts:481

Registers an endpoint handler with the server.

Parameters

Parameter	Type	Description
ep	Endpoint<US>	The endpoint handler to register

Returns

void

---

registerMiddleware()

registerMiddleware(mid): void

Defined in: net/server/server.ts:490

Registers a middleware handler with the server.

Parameters

Parameter	Type	Description
mid	Middleware<US>	The middleware handler to register

Returns

void

---

servicesForOrganization()

servicesForOrganization(orgId): Promise<ServerServices<US>>

Defined in: net/server/server.ts:428

Gets or creates server services for a given organization ID.

This method manages the lifecycle of server services for each organization, creating them on first access and caching them for subsequent requests.

Parameters

Parameter	Type	Description
orgId	string	The organization identifier

Returns

Promise<ServerServices<US>>

Promise resolving to the organization's server services

---

start()

start(): Promise<void>

Defined in: net/server/server.ts:628

Starts the server and all associated services.

Returns

Promise<void>

Promise that resolves when server is fully started

---

stop()

stop(): Promise<void>

Defined in: net/server/server.ts:697

Gracefully stops the server and all its services. Safe to call multiple times.

Shutdown sequence: stops accepting new connections, rejects new service lookups via _stopping flag, then flushes and closes all databases. Already-dispatched request handlers may still be running during flush — there is no request-draining mechanism.

Returns

Promise<void>

---

updateStaticAssets()

updateStaticAssets(assets): void

Defined in: net/server/server.ts:512

Updates the static assets configuration for the server and all existing organization services.

This is primarily used by the live-reload debug server functionality to update static assets without requiring a full server restart.

Parameters

Parameter	Type	Description
assets	StaticAssets	The new static assets configuration to apply

Returns

void