server

Imported from RayhanHamada/raurus (packages/server/AGENTS.md). Install upstream with npx skills add RayhanHamada/raurus --skill server. Copyright stays with the author.

Package Agent Guide

Package Context

This package is @raurus/server, a contract-first HTTP server built on oRPC. It implements the shared contracts from @raurus/contract using @orpc/server and exposes an RPCHandler-backed fetch handler. It uses its own src/logger/ module (LogTape wrapper) for structured logging and never calls configure() itself — that is the responsibility of the consuming application.

Architecture

src/
├── index.ts             # Public barrel — exports raurus and CreateRuntimeOptions from src/runtime/
├── core/
│   ├── index.ts              # Barrel: re-exports errors + types + constants from @raurus/contract
│   ├── errors.ts             # AdapterError — typed error with FailureCode
│   ├── types.ts              # Domain types, adapter contracts, factories
│   └── types.test.ts         # Vitest type-level tests
├── adapters/
│   ├── index.ts              # Barrel: re-exports all adapters
│   ├── libsql/index.ts       # libsql-based database adapter
│   └── s3mini/index.ts       # S3-compatible storage adapter backed by s3mini
├── logger/
│   ├── config.ts             # logTapeConfig (Config) + per-category level tables + initializeLogger
│   ├── get-logger.ts         # getLogger factory (["raurus", ...rest] categories)
│   └── index.ts              # Barrel: re-exports config + get-logger
└── runtime/
    ├── index.ts          # Named export: raurus (alias for createRuntime) + CreateRuntimeOptions
    ├── models.ts         # failureCodeToStatus mapper (FailureCode → HTTP status)
    ├── routes.ts         # oRPC procedure implementations — wraps @raurus/contract contracts via implement()
    ├── runtime.ts        # createRuntime() — async factory, inits adapters, returns { fetch, close }
    └── utils.ts          # Logger instance (getLogger("server")) + initializeLogger re-export

tsdown.config.ts          # Build config — entry: src/index.ts, src/core/index.ts, src/runtime/index.ts, src/logger/index.ts, src/adapters/index.ts, src/adapters/*/index.ts

Key Concepts

• Single public export — raurus() from @raurus/server is the only entry point. It is async: await raurus({...}) creates a fetch-compatible runtime with both adapters already initialized. CreateRuntimeOptions is also exported as a type for consumers. Router (the oRPC router type derived from typeof router) is exported so that RPC clients (e.g., RPCLink) can consume the server's typed procedure signatures.
• Contract-first — Routes are defined in @raurus/contract (Valibot schemas + oRPC contracts). The server package implements them via @orpc/server's implement(contracts).$context<ServerContext>(). Input validation is handled entirely by the contract layer.
• CreateRuntimeOptions — baseUrl: string | URL (required), databaseAdapter: RuntimeDatabaseAdapter (required), storageAdapter: RuntimeStorageAdapter (required), debug?: boolean (default false).
• Context-based dependency injection — routes.ts defines a ServerContext interface { db: RuntimeDatabaseAdapter; storage: RuntimeStorageAdapter }. The implement(contracts).$context<ServerContext>() threads adapters to every handler via the oRPC context, replacing Elysia's .decorate() pattern.
• Error handling — Adapter methods throw AdapterError (an Error with a required FailureCode). Procedure handlers catch it via a shared toORPCError helper and throw ORPCError with the mapped status from failureCodeToStatus(code). NOT_FOUND maps to the contract's NOT_FOUND error; everything else maps to NOT_IMPLEMENTED. Non-AdapterError exceptions (programmer bugs) propagate untouched. The NOT_IMPLEMENTED error carries { name: string } data as defined in the contract. The CONFLICT error carries { name: string, detail?: string } and is used when a placeholder type mismatch is detected.
• Logging — Use getLogger("server") from @/logger (re-exported as @raurus/server/logger) for runtime, route, and adapter logs. Adapter modules scope their logger (getLogger("server", "libsql")). The server package only obtains loggers; the consuming app is responsible for calling configure() from @logtape/logtape once at startup (or initializeLogger() from @raurus/server/logger for quick debug-mode setup).
• Fetch-compatible — createRuntime() returns { fetch, close }, backed by RPCHandler from @orpc/server/fetch, compatible with Bun, Cloudflare Workers, and other WinterCG runtimes. The close() method gracefully shuts down both adapters. In serverless environments like Cloudflare Workers, there is no automatic shutdown hook — close() must be called explicitly by the consumer (e.g., in a scheduled handler or via a custom lifecycle wrapper). new URL() is used for baseUrl parsing instead of URL.parse() for broad Workers compatibility date support.
• Adapter lifecycle — Every adapter implements init(), close(), and checkConnection() from AdapterLifecycle. createRuntime() awaits both init() calls concurrently at startup, so backend failures are fail-fast, not first-request. init() is idempotent. checkConnection() is a pure health probe — it resolves void when healthy, throws AdapterError (CONNECTION) when not, and never triggers init(). Adapter factories are synchronous and pure — they construct the adapter object but perform no side effects. All setup goes in init(). close() is idempotent; after close(), every other method rejects with AdapterError (CONFIGURATION).
• Storage capabilities — Partial storage implementations declare capabilities: { presignedUpload, delete }. All methods are required on the interface; an adapter with a false flag rejects that method with AdapterError (NOT_IMPLEMENTED). Routes check the flag first and throw ORPCError("NOT_IMPLEMENTED", { status: 501 }) — never use a 400 status for a missing capability.
• Metadata upsert procedure — upsertMetadata delegates directly to db.upsertContentMetadata(). Each (placeholder_id, pathname) pair is an independent row — the same placeholder_id may exist on different pages with different types. Throws ORPCError("NOT_IMPLEMENTED", ...) on adapter failure.
• Placeholder storage — A single raurus_placeholders table stores all placeholder data with composite primary key (placeholder_id, pathname). There is no separate definitions table and no type-enforcement layer — the server simply upserts whatever the client sends. init() uses CREATE TABLE IF NOT EXISTS (idempotent, no sentinel query).
• Metadata read procedure — listMetadataByPathname delegates to db.listContentMetadataByPath() and returns all placeholder metadata for a given pathname. Used by the frontend to hydrate placeholder values on page load. Rows with unknown type values are skipped with a warning log.
• Presigned upload URL procedure — getPresignedUploadUrl checks storage.capabilities.presignedUpload, then delegates to storage.createPresignedUploadUrl(). Throws ORPCError("NOT_IMPLEMENTED", { status: 501 }) when the capability is off.
• Delete asset procedure — deleteAsset checks storage.capabilities.delete, then delegates to storage.deleteAsset(). Throws ORPCError("NOT_FOUND", { status: 404 }) on AdapterError with NOT_FOUND, and ORPCError("NOT_IMPLEMENTED", ...) otherwise.
• Failure code → HTTP status — models.ts exports failureCodeToStatus(code: FailureCode): number that maps a FailureCode to an HTTP status. Used by toORPCError in procedure handlers. The code is always present on AdapterError, so no fallback is needed.

Package Standards

• Keep runtime logic under src/runtime/ — src/index.ts is a thin barrel that re-exports raurus and CreateRuntimeOptions from ./runtime
• routes.ts is the single file defining procedure implementations using implement() from @orpc/server and the contracts from @raurus/contract
• Export the runtime factory as raurus from src/runtime/index.ts
• Use the in-tree logger (@/logger, published as @raurus/server/logger) for all logs; create module-level const log = getLogger("server", "<area>") loggers and do not call configure() inside this package
• When an adapter call throws, log error.message and route it through the toORPCError helper in routes.ts with a descriptive fallback name
• When a storage capability is off, check storage.capabilities.<flag> and throw ORPCError("NOT_IMPLEMENTED", { status: 501 }) — never use a 400 status for a missing capability
• All validation is defined in @raurus/contract — do not duplicate schemas in the server package

Workflow

• Read the root AGENTS.md before planning or implementing changes

• Build with bun run build (tsdown with ESM output)

• Run tests with bun run test (vitest)

• Type-check with bun run typecheck

• Build uses tsdown with entries src/index.ts, src/core/index.ts, src/runtime/index.ts, src/logger/index.ts, src/adapters/index.ts, and src/adapters/*/index.ts — category barrel exports and individual adapters are auto-picked up

• Logger lives in src/logger/ — a LogTape wrapper exposing getLogger, logTapeConfig, initializeLogger, RaurusPackageNames (["core", "server"]), and per-category level tables. Consumers import it via @raurus/server/logger.

• utils.ts exports a module-level log logger instance and re-exports initializeLogger from @/logger

• Adapters live in per-adapter directories under src/adapters/ (libsql/, s3mini/), each with its own index.ts, all barrel-exported from src/adapters/index.ts. Importable as @raurus/server/adapters, @raurus/server/adapters/libsql, @raurus/server/adapters/s3mini.

• Adapters extend the base config interfaces from @raurus/server/core (RuntimeDatabaseAdapterBaseConfig, RuntimeStorageAdapterBaseConfig); factory functions return the adapter directly (the RuntimeDatabaseAdapterFactory / RuntimeStorageAdapterFactory types exist for custom adapters)

• Database adapters — currently only libsql (LibsqlDatabaseAdapterConfig, libSqlDatabaseAdapter). The CreateRuntimeOptions field is named databaseAdapter.

• Storage adapters — currently only s3mini (S3MiniStorageAdapterOptions, s3MiniStorageAdapter). The CreateRuntimeOptions field is named storageAdapter.

• RuntimeDatabaseAdapter exposes upsertContentMetadata (resolves void) and listContentMetadataByPath (resolves the metadata list) — both required. upsertContentMetadata takes a discriminated payload union ({ type: photo, assetKey } | { type: text, text } | { type: link, text, link }). Link payloads carry both text (display/anchor text) and link (href URL).

• RuntimeStorageAdapter requires createPresignedUploadUrl (resolves { url, headers? }) and deleteAsset (resolves void), plus capabilities: { presignedUpload, delete } flags for partial implementations

• createRuntime() is the async runtime factory function defined in runtime.ts; it is re-exported as raurus from runtime/index.ts. The return type includes a close() method for graceful shutdown. Always await it.

• Adapter factories are synchronous and pure — all setup side effects (connections, schema migrations, authentication) go in init(), which createRuntime() awaits at startup. Config validation may throw AdapterError (CONFIGURATION) synchronously in the factory.

• New adapters need no lifecycle wrapper — just implement AdapterLifecycle (init/close/checkConnection) plus the kind interface, declare an id, and (for storage) a capabilities map. Each adapter guards its own methods against post-close() calls with AdapterError (CONFIGURATION).

• utils.ts exports a module-level log logger instance and re-exports initializeLogger from @/logger

• The @raurus/contract package is a workspace:* dependency; contracts are imported via import { contracts } from "@raurus/contract". The baseOc contract defines shared error types: NOT_IMPLEMENTED and CONFLICT, with NOT_FOUND added on deleteAsset.

• The libsql database adapter creates a single raurus_placeholders table on init() via CREATE TABLE IF NOT EXISTS with composite primary key (placeholder_id, pathname) and columns: type, asset_key, text_content, link_url, updated_at.

• Third-party drivers (@libsql/client, s3mini) are peer dependencies — consumers install them. Mirror them in devDependencies so tests and builds resolve locally. Cloudflare Workers compatibility is a hard constraint on driver choice.

• @orpc/server is used for the RPCHandler import at @orpc/server/fetch