@owlmeans/server-api 0.1.18-rc.44 → 0.1.18-rc.46

package/README.md

@@ -10,7 +10,7 @@ only when composing a context without that package. WebSocket routes belong to
 ## Installation
 
 ```bash
-bun add @owlmeans/server-api@^0.1.18-rc.44
+bun add @owlmeans/server-api@^0.1.18-rc.46
 ```
 
 ## Concepts
@@ -240,7 +240,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.41
+npx @owlmeans/agent-skills@^0.1.18-rc.44
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-api",
-  "version": "0.1.18-rc.44",
-  "generatedAt": "2026-09-28T02:06:37.867Z",
+  "version": "0.1.18-rc.46",
+  "generatedAt": "2026-09-30T09:41:02.819Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-api/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: false
 
 # @owlmeans/server-api
 
-**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.44`
+**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.46`
 
 Make handlers from the protocol declaration so input and output types stay coupled to the shared
 contract:
@@ -38,6 +38,12 @@ export const serverBindings = [
 any protocol and receives all its typed sections plus request metadata. A successful callback
 return resolves the entrypoint with `EntrypointOutcome.Ok`; a thrown error rejects it.
 
+A body contract may be a scalar (`schema<string>({ type: 'string' })`, a number, a boolean): the
+server's JSON parser takes any JSON value, so `"abc"`, `42` or `false` reach the handler as that
+value. An unquoted string or an empty body under `application/json` is invalid JSON and answers
+400 before the handler runs — `@owlmeans/api` never sends either (it quotes a scalar body).
+`tests/json-body.spec.ts` runs it through `appendApiServer`.
+
 ## Wrap exactly once
 
 A handler is wrapped by `handlers<Context>()` exactly once — either shape above (create the bound
@@ -74,6 +80,9 @@ exposure) and a status from `errorStatus(error)` (`./utils`), resolved in this o
   that is understood and refused — and a missing configuration, a broken peer, a timeout or a bug
   stays 500, because monitoring, logs, proxies and retry logic read a 5xx as the server failing.
   The table and the leaf-class rule are the `error` skill's.
+- The storage refusals of `@owlmeans/resource` declare theirs: `UnknownRecordError` answers 404,
+  `RecordExists` 409, every other `ResourceError` 500 — so a handler that lets a `get()` miss
+  escape answers 404, and one reading a row the request did not address uses `load` instead.
 - Declare it on the class: `public static httpStatus = 409` (`override` only when an ancestor
   already declares one). The declaration is structural — the package declaring an error never
   imports `@owlmeans/server-api` — and a static property is inherited, so a subclass answers its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.44",
+  "version": "0.1.18-rc.46",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -33,14 +33,14 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.40",
+    "@owlmeans/api": "^0.1.18-rc.42",
     "@owlmeans/auth": "^0.1.18-rc.36",
-    "@owlmeans/auth-common": "^0.1.18-rc.40",
+    "@owlmeans/auth-common": "^0.1.18-rc.42",
     "@owlmeans/context": "^0.1.18-rc.32",
     "@owlmeans/error": "^0.1.18-rc.36",
     "@owlmeans/entrypoint": "^0.1.18-rc.37",
     "@owlmeans/route": "^0.1.18-rc.33",
-    "@owlmeans/server-context": "^0.1.18-rc.37",
+    "@owlmeans/server-context": "^0.1.18-rc.38",
     "@owlmeans/server-entrypoint": "^0.1.18-rc.36",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
@@ -53,6 +53,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/resource": "^0.1.18-rc.37",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",

package/tests/error-status.spec.ts

@@ -7,7 +7,11 @@ import { provideResponse } from '@owlmeans/entrypoint'
 import { errorExposure, errorStatus, handleError, INCIDENT_ID_HEADER } from '../src/utils/error.js'
 import { executeResponse } from '../src/utils/payload.js'
 import { AccessError, AuthFailedError } from '../src/errors.js'
-import { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND } from '@owlmeans/api'
+import { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND, httpStatusOf } from '@owlmeans/api'
+import {
+  MigrationError, MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError,
+  UnsupportedArgumentError, UnsupportedMethodError,
+} from '@owlmeans/resource'
 
 class OutOfCredit extends ResilientError {
   public static override typeName = 'ServerApiSpecOutOfCredit'
@@ -180,7 +184,7 @@ const answer = async (error: unknown, path: string = '/handle') => {
   return {
     status: reply.statusCode,
     body: reply.body,
-    incidentId: reply.headers[INCIDENT_ID_HEADER.toLowerCase()],
+    incidentId: reply.headers[INCIDENT_ID_HEADER.toLowerCase()] as string,
     retryAfter: reply.headers['retry-after'],
     denialKind: reply.headers[DENIAL_KIND_HEADER.toLowerCase()],
   }
@@ -294,3 +298,45 @@ describe('@owlmeans/server-api — auth status across a rebuild and duplicate mo
     expect((await answer(new ForeignEntitlementRefusal())).status).toBe(403)
   })
 })
+
+describe('@owlmeans/server-api — storage refusals of @owlmeans/resource', () => {
+  test('an absent record answers 404 and a taken id or key 409 — as thrown and after a marshal hop', async () => {
+    expect((await answer(new UnknownRecordError('shelf/3'))).status).toBe(404)
+    expect((await answer(new RecordExists('id-present'))).status).toBe(409)
+    expect((await answer(ResilientError.marshal(new UnknownRecordError('shelf/3')))).status).toBe(404)
+    expect((await answer(ResilientError.marshal(new RecordExists('isbn')))).status).toBe(409)
+    expect((await answer(new UnknownRecordError('shelf/3'), '/execute')).status).toBe(404)
+  })
+
+  test('a storage fault still answers 500', async () => {
+    for (const fault of [
+      new MisshapedRecord('x'), new RecordUpdateFailed('x'), new UnsupportedArgumentError('ttl'),
+      new UnsupportedMethodError('watch'), new MigrationError('x'),
+    ]) {
+      expect([fault.type, (await answer(fault)).status]).toEqual([fault.type, 500])
+    }
+  })
+
+  test('a development body rebuilds into the same class, and the status the client stamps agrees with it', async () => {
+    for (const [error, status] of [
+      [new UnknownRecordError('shelf/3'), 404], [new RecordExists('isbn'), 409],
+    ] as const) {
+      const response = await answer(error, '/handle-development')
+      expect(response.status).toBe(status)
+      // What `@owlmeans/api` does with a non-2xx body carrying the separator.
+      const rebuilt = Object.assign(ResilientError.ensure(response.body, true), { responseStatus: response.status })
+      expect(rebuilt.constructor).toBe(error.constructor)
+      expect(rebuilt.message).toBe(error.message)
+      expect(httpStatusOf(rebuilt)).toBe(status)
+    }
+    const rebuilt = ResilientError.ensure((await answer(new UnknownRecordError('shelf/3'), '/handle-development')).body, true)
+    expect((rebuilt as UnknownRecordError).id).toBe('shelf/3')
+  })
+
+  test('a production body is the incident id alone, under the declared status', async () => {
+    const response = await answer(new UnknownRecordError('shelf/3'))
+    expect(response.status).toBe(404)
+    expect(response.body).toBe(response.incidentId)
+    expect(response.body).not.toContain('shelf')
+  })
+})

package/tests/json-body.spec.ts

@@ -0,0 +1,72 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { AppType } from '@owlmeans/context'
+import { contract, protocol, schema, typed } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { bind } from '@owlmeans/server-entrypoint'
+import type { FastifyInstance } from 'fastify'
+import { handlers } from '../src/protocol.js'
+import { appendApiServer } from '../src/server.js'
+
+interface Echo { value: unknown, type: string }
+
+const echoOf = <T>(alias: string, body: ReturnType<typeof schema<T>>) => protocol(
+  route(`server-api-test:${alias}`, `/echo/${alias}`, backend(null, RouteMethod.POST)),
+  contract(body, typed<Echo>()),
+)
+
+const text = echoOf('text', schema<string>({ type: 'string' }))
+const count = echoOf('count', schema<number>({ type: 'number' }))
+const flag = echoOf('flag', schema<boolean>({ type: 'boolean' }))
+const record = echoOf('record', schema<{ a: number }>({ type: 'object', properties: { a: { type: 'number' } }, required: ['a'] }))
+
+/**
+ * A scalar JSON body through the package's own server — `appendApiServer`, its Fastify instance,
+ * its body validation and a protocol-bound handler — exactly as `@owlmeans/api` now sends it:
+ * JSON text. The client half of the round trip is `@owlmeans/api`'s `body.spec.ts`.
+ */
+describe('@owlmeans/server-api — a scalar JSON body', () => {
+  let server: FastifyInstance
+  let context: ServerContext<ServerConfig>
+
+  beforeAll(async () => {
+    const service = 'server-api-tests'
+    context = makeServerContext(config<ServerConfig>(service, {
+      services: { [service]: { service, type: AppType.Backend, host: '127.0.0.1', default: true } },
+    } as Partial<ServerConfig>)) as ServerContext<ServerConfig>
+    const served = appendApiServer(context)
+    const api = handlers<ServerContext<ServerConfig>>()
+    for (const echo of [text, count, flag, record]) {
+      context.registerEntrypoint(bind(echo, api.request(echo, async request => ({ value: request.body, type: typeof request.body }))))
+    }
+    context.configure()
+    await context.init()
+    server = served.getApiServer().server
+    await server.ready()
+  })
+
+  afterAll(async () => { await server?.close() })
+
+  const post = async (alias: string, payload: string, type: string = 'application/json') =>
+    await server.inject({ method: 'POST', url: `/echo/${alias}`, headers: { 'content-type': type }, payload })
+
+  const echoed = async (alias: string, payload: string): Promise<Echo> => (await post(alias, payload)).json<Echo>()
+
+  test('a JSON string, number or boolean reaches the handler as that value', async () => {
+    expect(await echoed('text', '"abc"')).toEqual({ value: 'abc', type: 'string' })
+    expect(await echoed('text', '""')).toEqual({ value: '', type: 'string' })
+    expect(await echoed('text', '"123"')).toEqual({ value: '123', type: 'string' })
+    expect(await echoed('count', '42')).toEqual({ value: 42, type: 'number' })
+    expect(await echoed('flag', 'false')).toEqual({ value: false, type: 'boolean' })
+  })
+
+  test('an object body is unchanged', async () => {
+    expect(await echoed('record', '{"a":1}')).toEqual({ value: { a: 1 }, type: 'object' })
+  })
+
+  test('an unquoted string or an empty JSON body is refused with 400 — what the client no longer sends', async () => {
+    expect((await post('text', 'abc')).statusCode).toBe(400)
+    expect((await post('text', '')).statusCode).toBe(400)
+  })
+})