Servers

Official servers

Quick start

import { serve } from '@hono/node-server'
import { DefaultEventBridge } from '@purista/core'
import { honoV1Service } from '@purista/hono-http-server'

const eventBridge = new DefaultEventBridge()
await eventBridge.start()

// Add your service
const myService = await myV1Service.getInstance(eventBridge)
await myService.start()

// Create and start the Hono HTTP service
const honoService = await honoV1Service.getInstance(eventBridge, {
  serviceConfig: {
    enableDynamicRoutes: false,
  },
})
honoService.registerService(myService)
await honoService.start()

// Open a network socket (Node.js — swap for Bun.serve or Deno.serve as needed)
serve({
  fetch: honoService.app.fetch,
  port: 3000,
})

Community servers

When to use

• You need REST endpoints and OpenAPI over command definitions.
• You need SSE endpoints over stream definitions.
• You want transport concerns separated from business logic.
• You want runtime flexibility (Node.js, Bun, Deno).
• You want standardized HTTP error responses via RFC 9457 Problem Details.

Common pitfalls

• assuming honoV1Service.start() also opens a network socket
• missing auth middleware/protection handlers
• not aligning command parameter schema with query/path params

Checklist

• @purista/hono-http-server is installed
• routes are registered explicitly via registerService(...) or via dynamic mode
• health endpoint is enabled explicitly when needed (enableHealth: true)
• command endpoints are mapped to JSON responses
• framework-generated HTTP errors are exposed as application/problem+json
• clients can request text/markdown for the same normalized error details
• stream endpoints are mapped to text/event-stream (SSE) responses
• Hono server socket is explicitly started for your runtime
• auth, OpenAPI metadata, and graceful shutdown are configured

Error responses

@purista/hono-http-server maps PURISTA framework errors to RFC 9457 Problem Details.

Default error response content type:

• application/problem+json

Optional negotiated representation:

• text/markdown when the client sends Accept: text/markdown

This applies to framework-generated HTTP errors such as:

• validation failures
• unsupported request content type
• route-not-found handling
• handled and unhandled command execution errors

OpenAPI output documents the canonical JSON error contract as application/problem+json and also declares the optional Markdown representation.

If you want dereferenceable problem type URIs, configure the Hono service with problemDetails.typeBaseUri. Without that setting, the adapter uses about:blank instead of hardcoded framework URLs.

const server = await honoV1Service.getInstance(eventBridge, {
  serviceConfig: {
    enableDynamicRoutes: false,
    problemDetails: {
      typeBaseUri: 'https://api.example.com/problems',
    },
  },
})
server.registerService(myService)