Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

### Breaking Changes

- `HttpServerInstance.stop()` and `Server.stop()` now return `Promise<void>`
and must be awaited. The promise resolves only after the listener is closed
and the port is free. A caller that ignores it can return before in-flight
requests finish, and a restart can fail to bind the port.
- **Store path must be absolute and non-root.** `DBInstanceConfig.path` now
throws `DBInstanceConfig.path must be an absolute, non-root path` for
relative paths, the empty string, and filesystem roots such as `/`. Resolve
Expand All @@ -42,6 +46,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

### Fixed

- A server `stop()` that races an in-flight `start()` now waits for that start
to settle before closing the listener, instead of returning early and
leaving a bound server behind. A `start()` after a failed teardown retries
cleanly, and a later `force` stop interrupts an in-progress drain even when
the stop is queued behind a restart. Drain-then-close ordering is unchanged,
and force or timeout still never cancel application handlers.
- `goatdb init` now scaffolds `.gitignore` and `.npmrc` again when run from the
published npm package. `npm pack` drops dotfile sources, so the templates use
plain names (`gitignore`, `npmrc`) that `init` maps back to their dotted
Expand Down Expand Up @@ -96,6 +106,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
call, bounded by a 180s timeout. Exact pins let a transitive peer resolve a
newer `react` than `react-dom`, which crashes at runtime with "Incompatible
React versions".
- `stop()` is graceful by default: in-flight requests and responses finish,
new requests receive `503 Service Unavailable` with `connection: close`, and
the listener closes when the drain ends. `force: true` closes immediately
and `timeoutMs` bounds the drain (default 10s, an integer from 0 to
2147483647; other values reject and leave the server running). Neither
cancels application handlers.
- HTTP health checks from the `awsalb` host now accept `http` and `https`
URLs on any port and ignore the query string; the path must be exactly
`/healthy`. The comparison is now case-sensitive, so a mixed-case probe such
as `/HEALTHY` returns 404; the `/healthy` endpoint itself still matches
case-insensitively. Keep ALB health-check paths lowercase.

## [0.6.1] - 2026-09-01

Expand Down
4 changes: 3 additions & 1 deletion cli/templates/deno/server/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import * as path from '@std/path';
import { prettyJSON } from '@goatdb/goatdb';
import {
type BuildInfo,
DEFAULT_STOP_TIMEOUT_MS,
Server,
staticAssetsFromJS,
} from '@goatdb/goatdb/server';
Expand Down Expand Up @@ -76,7 +77,8 @@ async function main(): Promise<void> {
const shutdown = () => {
if (stopping) return;
stopping = true;
setTimeout(() => Deno.exit(1), 5000);
// The drain budget plus a margin for database flush.
setTimeout(() => Deno.exit(1), DEFAULT_STOP_TIMEOUT_MS + 1_000);
server.stop().then(() => Deno.exit(0)).catch((e) => {
console.error(e);
Deno.exit(1);
Expand Down
8 changes: 7 additions & 1 deletion cli/templates/node/server/server-sea.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@ declare module 'node:sea' {

import {
type BuildInfo,
DEFAULT_STOP_TIMEOUT_MS,
Server,
staticAssetsFromJS,
} from '@goatdb/goatdb/server';
import { prettyJSON, type ReadonlyJSONObject } from '@goatdb/goatdb';
import { registerSchemas } from '../common/schema.js';
import { basename, join } from 'node:path';
import process from 'node:process';

interface Arguments {
path?: string;
Expand Down Expand Up @@ -181,7 +183,11 @@ async function main(): Promise<void> {
const shutdown = () => {
if (stopping) return;
stopping = true;
const forceExit = setTimeout(() => process.exit(1), 5_000);
// The drain budget plus a margin for database flush.
const forceExit = setTimeout(
() => process.exit(1),
DEFAULT_STOP_TIMEOUT_MS + 1_000,
);
forceExit.unref();
server.stop().then(() => process.exit(0)).catch((e) => {
console.error(e);
Expand Down
8 changes: 7 additions & 1 deletion cli/templates/node/server/server.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import {
type BuildInfo,
DEFAULT_STOP_TIMEOUT_MS,
Server,
staticAssetsFromJS,
} from '@goatdb/goatdb/server';
Expand All @@ -9,6 +10,7 @@ import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import { fileURLToPath } from 'node:url';
import { dirname, join, resolve } from 'node:path';
import process from 'node:process';
// These imported files will be automatically generated during compilation
import encodedStaticAssets from '../build/staticAssets.json' with {
type: 'json',
Expand Down Expand Up @@ -86,7 +88,11 @@ async function main(): Promise<void> {
const shutdown = () => {
if (stopping) return;
stopping = true;
const forceExit = setTimeout(() => process.exit(1), 5000);
// The drain budget plus a margin for database flush.
const forceExit = setTimeout(
() => process.exit(1),
DEFAULT_STOP_TIMEOUT_MS + 1_000,
);
forceExit.unref();
server.stop().then(() => process.exit(0)).catch((e) => {
console.error(e);
Expand Down
4 changes: 3 additions & 1 deletion docs/api/classes/server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -115,11 +115,13 @@ Starts the server and all associated services.

### stop()

**<code>stop(): Promise&lt;void&gt;</code>**
**<code>stop(options?: HttpServerStopOptions): Promise&lt;void&gt;</code>**

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

`timeoutMs` bounds the drain, not the final listener close. `force` skips the drain. Direct `processRequest` calls are not tracked; embedded servers must drain them.

### updateStaticAssets()

**<code>updateStaticAssets(assets: StaticAssets): void</code>**
Expand Down
8 changes: 8 additions & 0 deletions logging/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ import type { EmailType } from './metrics.ts';
* impossible
* - FailedAssertion: Used when an assertion check fails
* - UncaughtServerError: Used for unhandled exceptions on the server
* - HttpServerError: Emitted by a listening HTTP server after it started
* - ServerStartFailed: Emitted when a server start aborts and rolls back
* - JsonLogWorkerError: Used when the JSON log worker fails or dies
* - MissingConfiguration: Used when required configuration options are missing
*/
Expand All @@ -20,6 +22,8 @@ export type DeveloperError =
| 'NotReached'
| 'FailedAssertion'
| 'UncaughtServerError'
| 'HttpServerError'
| 'ServerStartFailed'
| 'JsonLogWorkerError';

/**
Expand Down Expand Up @@ -57,6 +61,8 @@ export interface LogEntryDeveloperError extends BaseErrorLogEntry {
* - DuplicateFailed: Failed to handle duplicate message
* - SessionError: Error occurred while handling session
* - EmailSendFailed: Failed to send email
* - ServerStopFailed: HTTP server stop failed
* - StopTimeout: HTTP server drain timed out
*/
export type OperationalError =
| 'FetchError'
Expand All @@ -70,7 +76,9 @@ export type OperationalError =
| 'SessionError'
| 'EmailSendFailed'
| 'MissingConfiguration'
| 'ServerStopFailed'
| 'StorageError'
| 'StopTimeout'
| 'UnknownWorkerResponse'
| 'ValidationError';

Expand Down
10 changes: 9 additions & 1 deletion net/server/health.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@ import type { Endpoint, ServerServices } from './server.ts';
import type { Schema } from '../../cfds/base/schema.ts';
import type { GoatRequest, ServeHandlerInfo } from './http-compat.ts';

/**
* Canonical health-check path, shared by the endpoint and the ALB short-circuit.
* WHY normalized here: the endpoint lowercases probe paths before comparison,
* so a mixed-case literal would silently stop matching. Normalizing at the
* definition keeps both comparisons on one canonical value.
*/
export const kHealthCheckPath = '/healthy'.toLowerCase();

/**
* Endpoint that handles health check requests.
*
Expand All @@ -21,7 +29,7 @@ export class HealthCheckEndpoint<US extends Schema> implements Endpoint<US> {
return false;
}
const path = new URL(req.url).pathname.toLowerCase();
return path === '/healthy';
return path === kHealthCheckPath;
}

processRequest(
Expand Down
Loading
Loading