Server and deployment

Ramose.Server provisions the Cloudflare data plane for one application: the public Worker, authoritative database writers, query execution, object storage, synchronization, optional MCP endpoint, and test-gated instrumentation.

New here? Start with Deploy Ramose.

Resource declaration

import * as Cloudflare from "alchemy/Cloudflare"
import * as Ramose from "ramose"

const Store = Cloudflare.R2.Bucket("TasksStore", {
  name: "ramose-tasks-store",
})

export const data = Ramose.Server("Tasks", {
  main: import.meta.resolve("./peer.ts"),
  storage: Store,
  auth,
})

The resource owns platform bindings and compatibility configuration. It does not accept a root schema. The Worker entry assembles the explicit deployment:

import * as Effect from "effect/Effect"
import {
  QueryReplicaDO,
  createServer,
  createTransactorDO,
  deployOperationCatalogs,
} from "ramose/worker"
import { deployment } from "./domain"

const operationCatalogs = await Effect.runPromise(
  deployOperationCatalogs(deployment),
)

export default createServer({ operationCatalogs })
export { QueryReplicaDO }
export const TransactorDO = createTransactorDO(operationCatalogs)

deployment contains the named schema as root and the database deployments that use it. Identity configuration, routes, storage, and observability remain deployment resource settings.

Public routes

Route	Purpose
`GET /health`	Unauthenticated liveness without catalog or data disclosure
`/db/*`	Authorized browser and server data plane
`POST /mcp`	Optional Streamable HTTP MCP endpoint
OAuth metadata routes	Protected-resource and authorization discovery for MCP clients

Database and catalog internal identifiers are never public selectors. Requests derive the authorized database from verified identity.

Database runtime

Each database has one authoritative commit order and independently scalable read/synchronization state.

Queries and operations remain inside one database. Cross-database workflows must make intermediate states and recovery explicit.

Catalog installation

Deployment validates definition identities, stored value representations, trait conformance, operation schemas, and compiled policy. Incompatible catalog changes fail before they can reinterpret existing data.

Use staged additive changes and explicit migrations. Offline replicas and old clients may reconnect after a deployment, so compatibility is a protocol concern as well as a storage concern.

Synchronization

The browser restores a persistent snapshot, resumes from its durable cursor, and receives authorized changes. If incremental history is unavailable or authorization changes invalidate the view, the server issues a safe resnapshot path. Clients never merge facts from a different principal or database identity.

MCP

The same catalog, policy, query runtime, database target, and operations back describe, query, and mutate. Configure OAuth metadata and query/discovery budgets before exposing the endpoint publicly.

Test hooks

Integration instrumentation is inert unless both RAMOSE_TEST_HOOKS=1 and a non-production stage are present. Production must fail closed even if one guard is misconfigured. Test routes are not part of the public API.

Observability

Collect health, request latency, database activation, snapshot size, resume/resnapshot frequency, query budget failures, operation receipt outcomes, storage faults, and synchronization lag. Correlate requests and receipts with opaque safe identifiers; redact tokens and application payloads.

Limits and retention

Set explicit limits for query work, projection width, recursion, pages, discovery, snapshot size, retained history, queued invocations, and request bodies. Defaults should protect a multi-tenant deployment; raise a limit only with measured workload evidence.