Skip to main content

Server

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.

Constructor​

new Server(options: ServerOptions<US>)

Methods​

orgIds()​

orgIds(): Iterable<string>

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

processRequest()​

processRequest(goatReq: GoatRequest<>, info: ServeHandlerInfo): Promise<Response<>>

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

registerEndpoint()​

registerEndpoint(ep: Endpoint<US>): void

Registers an endpoint handler with the server.

registerMiddleware()​

registerMiddleware(mid: Middleware<US>): void

Registers a middleware handler with the server.

servicesForOrganization()​

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

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.

start()​

start(): Promise<void>

Starts the server and all associated services.

stop()​

stop(): Promise<void>

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

updateStaticAssets()​

updateStaticAssets(assets: StaticAssets): void

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.