@kelpie/server 0.2.0 → 0.3.1

package/src/runtime/registry.ts

@@ -43,22 +43,32 @@ export interface ModuleRouter {
   readonly router: Hono
 }
 
+/**
+ * What `registerModules` needs.
+ *
+ * Every optional field spells out `| undefined`, which is not noise. Under
+ * `exactOptionalPropertyTypes` an omitted key and a key holding `undefined` are
+ * different types, and an assembly building these options has the second:
+ * `readModuleConfigFile` returns `undefined` when no override file is
+ * configured. Without it, core hands a caller a value its own runtime refuses.
+ * None of the four fields tells the two cases apart.
+ */
 export interface ModuleRuntimeOptions {
   readonly modules: readonly KelpieModule[]
   /** Raw variables. Each module validates the slice it needs via `context.config`. */
   readonly environment: Environment
   readonly logger: Logger
   /** Injected so a test can watch what core modules subscribe to. Defaults to a fresh bus. */
-  readonly events?: EventBus
+  readonly events?: EventBus | undefined
   /** Injected so a test can grant or deny before core modules register. */
-  readonly entitlements?: EntitlementRegistry
+  readonly entitlements?: EntitlementRegistry | undefined
   /** The database, transaction scope, and collaborators every module builds on. */
   readonly services: ModuleServices
   /**
    * The deploy-time module override (`lib/moduleConfig.ts`), parsed. A locked
    * module id wins over whatever a workspace's own settings say.
    */
-  readonly moduleConfig?: Readonly<Record<string, boolean>>
+  readonly moduleConfig?: Readonly<Record<string, boolean>> | undefined
   /**
    * Resolves the caller of a REST request, the same way every route already
    * does (`modules/auth/credentials.ts`), so a non-structural module's router
@@ -70,7 +80,7 @@ export interface ModuleRuntimeOptions {
    * every test that does not exercise module toggling wants without having to
    * say so.
    */
-  readonly resolveActor?: (context: Context) => Promise<Actor>
+  readonly resolveActor?: ((context: Context) => Promise<Actor>) | undefined
 }
 
 /** Contributions accumulate here, one mutable set per registration pass. */

package/src/schema/index.ts

@@ -28,3 +28,4 @@ export * from '../modules/import-export/schema.ts'
 export * from '../modules/agent-tasks/schema.ts'
 export * from '../modules/webhooks/schema.ts'
 export * from '../modules/integrations/schema.ts'
+export * from '../modules/rate-limit/schema.ts'

package/src/testing/app.ts

@@ -6,6 +6,8 @@ import type { Actor } from '../lib/actor.ts'
 import type { Environment } from '../lib/config.ts'
 import type { DatabaseProbe } from '../lib/database.ts'
 import { createLogger } from '../lib/logger.ts'
+import { rateLimitConfigFrom, rateLimitConfigSchema } from '../lib/rateLimit.ts'
+import type { RateLimitConfig } from '../lib/rateLimit.ts'
 import type { KelpieModule } from '../runtime/module.ts'
 import type { ModuleContributions } from '../runtime/registry.ts'
 import type { EntitlementRegistry } from '../runtime/entitlements.ts'
@@ -14,6 +16,19 @@ import { TEST_ENVIRONMENT } from './environment.ts'
 import { createTestServices } from './services.ts'
 import type { TestServices } from './services.ts'
 
+/** The same defaults `loadConfig` produces from an empty environment: one source of numbers for both. */
+const DEFAULT_TEST_RATE_LIMIT: RateLimitConfig = rateLimitConfigFrom(rateLimitConfigSchema.parse({}))
+
+/**
+ * A caller's IP, for tests. Real entry points resolve this from the socket
+ * (`apps/kelpie/src/server.ts`); a test using `app.request()` has no socket, so
+ * it reads `X-Forwarded-For` when a test sets one to simulate distinct
+ * callers, falling back to a fixed address for everything else.
+ */
+function testClientIp(context: Context): string {
+  return context.req.header('X-Forwarded-For') ?? '203.0.113.1'
+}
+
 /**
  * Assembles an app for tests. Unlike the real boot it defaults every dependency,
  * because a test that has to spell out an environment it does not care about
@@ -38,6 +53,10 @@ export interface TestAppOptions {
    * route behaves as it did before module toggling existed.
    */
   readonly resolveActor?: (context: Context) => Promise<Actor>
+  /** Defaults to the same numbers `loadConfig` would, from an empty environment. */
+  readonly rateLimit?: RateLimitConfig
+  /** Defaults to reading `X-Forwarded-For`, so a test can simulate distinct callers. */
+  readonly resolveClientIp?: (context: Context) => string
 }
 
 export interface TestApp {
@@ -73,6 +92,8 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
     credentials: { db: services.db, now: services.now },
     generateRequestId: options.generateRequestId ?? (() => 'req-test'),
     createId: services.createId,
+    rateLimit: options.rateLimit ?? DEFAULT_TEST_RATE_LIMIT,
+    resolveClientIp: options.resolveClientIp ?? testClientIp,
   })
 
   return { app, contributions, logLines, services }

package/src/webBundle.ts

@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { serveStatic } from '@hono/node-server/serve-static'
+import type { Hono, MiddlewareHandler } from 'hono'
+
+import type { AppBindings } from './app.ts'
+import { MCP_ROUTE_PREFIX } from './modules/mcp/index.ts'
+
+/**
+ * Serves a built web bundle from the same origin as the API.
+ *
+ * `createApp` answers data and nothing else. In development the Vite dev server
+ * builds the pages and proxies `/v1` through to the API, so one address serves
+ * both. That proxy is doing two jobs: rebuilding on edit, which is development
+ * only, and putting the pages and the API on one origin, which is permanent.
+ * Nothing did the second job in production, so a deployed assembly answered API
+ * calls and served no pages at all.
+ *
+ * An assembly opts in by calling this after `createApp`, which is where the
+ * three assemblies (`apps/kelpie`, a scaffolded project, and `kelpie-cloud`)
+ * would otherwise each grow their own copy of the fallback rule below.
+ */
+
+export interface WebBundleOptions {
+  /** Directory holding the built `index.html` and its assets. */
+  readonly directory: string
+}
+
+/** The bundle directory does not hold a build. Thrown at boot, never per request. */
+export class WebBundleError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WebBundleError'
+  }
+}
+
+/**
+ * The prefixes `createApp` answers on.
+ *
+ * `/v1/public` needs no entry of its own: it sits under `/v1`. `MCP_ROUTE_PREFIX`
+ * is imported rather than written out, so moving the endpoint moves this with it.
+ */
+const API_PREFIXES: readonly string[] = ['/v1', MCP_ROUTE_PREFIX, '/healthz']
+
+function isApiRequest(path: string): boolean {
+  return API_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))
+}
+
+/**
+ * Restricts a handler to requests for the web app.
+ *
+ * The API exclusion is the point of the whole file. `app.notFound` renders
+ * `api.md`'s JSON 404, and it only fires when no route matched, so a bare
+ * catch-all registered after `createApp` would answer `GET /v1/typo` with the
+ * app shell and a 200. A client asking for data would get a web page and no
+ * indication it had misspelled anything.
+ *
+ * Methods are filtered for the same reason: `POST /v1/typo` is a wrong endpoint,
+ * not a page request, and only a `GET` or a `HEAD` can sensibly be answered with
+ * a document.
+ */
+function webRequestsOnly(handler: MiddlewareHandler): MiddlewareHandler {
+  return async (context, next) => {
+    const isDocumentRequest = context.req.method === 'GET' || context.req.method === 'HEAD'
+
+    if (!isDocumentRequest || isApiRequest(context.req.path)) {
+      return next()
+    }
+
+    return handler(context, next)
+  }
+}
+
+/**
+ * Mounts the bundle on an app built by `createApp`.
+ *
+ * Call it after `createApp` and before serving. Hono composes a request's
+ * handlers in registration order and stops at the first one that answers, so
+ * mounting last leaves every API route matching ahead of these two.
+ *
+ * @throws WebBundleError if the directory holds no `index.html`. A deployment
+ *   whose build did not run should stop at boot rather than serve an API with
+ *   invisible pages, which is the failure this function exists to remove.
+ */
+export function serveWebBundle(app: Hono<AppBindings>, options: WebBundleOptions): void {
+  const directory = resolve(options.directory)
+  const indexHtml = join(directory, 'index.html')
+
+  if (!existsSync(indexHtml)) {
+    throw new WebBundleError(
+      `No index.html in ${directory}. Point WEB_BUNDLE_DIR at a built web bundle, or run the web build first.`,
+    )
+  }
+
+  // Two registrations rather than one: `serveStatic` calls `next()` when it
+  // finds no file, which is exactly the signal the fallback needs. A request
+  // for a real asset is answered by the first and never reaches the second.
+  app.use('*', webRequestsOnly(serveStatic({ root: directory })))
+
+  // The single-page fallback. The app decides what to draw from the address, so
+  // a deep link to `/people/per_01J…` has to return the same `index.html` even
+  // though no file sits at that path.
+  //
+  // A missing asset gets the shell too, which is what every static SPA server
+  // does by default. Narrowing this by `Accept` would turn a stale asset
+  // reference into a clean 404, and would also turn `curl /people/per_01J…`
+  // into one, so it is left alone.
+  app.use('*', webRequestsOnly(serveStatic({ path: indexHtml })))
+}