# @purista/hono-http-server API

Package for using a Hono as webserver.

---
Canonical: /handbook/api/modules/_purista_hono-http-server/
Format: Markdown for agents
---

Package for using a Hono as webserver.

Package: `@purista/hono-http-server`

## Signature

```typescript
@purista/hono-http-server
```

## Examples

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

// create and init our eventbridge
const eventBridge = new DefaultEventBridge()
await eventBridge.start()

// add your service
const pingService = await pingV1Service.getInstance(eventBridge)
await pingService.start()

const honoService = await honoV1Service.getInstance(eventBridge, {
  serviceConfig: {
    enableDynamicRoutes: false,
  }
})
honoService.registerService(pingService)
await honoService.start()

const _serverInstance = serve({
  fetch: honoService.app.fetch,
  port: 3000,
})
```

## Members

### Classes

- `class HonoServiceClass<Bindings, Variables>` — PURISTA service that exposes command, stream and async queue-backed endpoints through Hono.

### Type Aliases

- `type AnyService = Service<any>` — Service instance accepted by the Hono HTTP projection registry.
- `type BindingsBase = EmptyObject` — Base Hono bindings type used by the Hono HTTP service.
- `type Config = void` — OpenAPI generation settings needed by HTTP helper functions.
- `type EndpointProtectMiddleware = (this: T, c: Context<{ Bindings: Bindings; Variables: Variables }>, next: Next) => Promise<void | Response>` — Middleware type for protected generated Hono endpoints.
- `type HealthFunction = (this: T) => Promise<void>` — Health callback for the Hono HTTP service.
- `type HonoServiceV1Config = z.output<typeof honoServiceV1ConfigSchema>` — Fully parsed Hono service config with defaults applied.
- `type HonoServiceV1ConfigPartial = z.input<typeof honoServiceV1ConfigSchema>` — Partial Hono service config accepted by `honoV1Service.getInstance`.
- `type HonoV1ServiceCommandsToRestApiInputPayload = z.output<typeof honoV1ServiceCommandsToRestApiInputPayloadSchema>` — Payload shape for service metadata messages that trigger dynamic HTTP endpoint registration.
- `type ProblemDetails = void` — RFC 9457-style problem details response returned by generated Hono endpoints.
- `type ProblemTypeConfig = void` — Controls generated problem type URIs.
- `type ProtocolSseEvent = void` — Protocol-native SSE event passed through by stream handlers.
- `type PuristaOpenApiOperationOwner = void` — PURISTA owner metadata attached to generated OpenAPI operations.
- `type StreamTransportFramePayload = void` — Normalized payload shape used by HTTP stream transport frames.
- `type VariablesBase = void` — Hono variables read by generated PURISTA HTTP handlers.

### Variables

- `const DEFAULT_API_MOUNT_PATH: "/api"` — Default base path for generated HTTP command and stream endpoints.
- `const ExternalDocumentationObjectSchema: ZodObject<{ description: ZodOptional<ZodString>; url: ZodString }, $strip>` — Schema for OpenAPI external documentation objects.
- `const getQueryDefintion: (queryDefinition: QueryParameter<Record<string, unknown>>[] | undefined, parameterschema?: SchemaObject) => ParameterObject[]` — Backward-compatible alias for the misspelled query definition helper.
- `const honoServiceInfo: ServiceInfoType` — Service metadata for version 1 of the built-in Hono HTTP service.
- `const honoServiceV1ConfigSchema: ZodObject<{ apiMountPath: ZodDefault<ZodOptional<ZodString>>; autoRegisterServicesFromConfig: ZodDefault<ZodOptional<ZodBoolean>>; enableDynamicRoutes: ZodDefault<ZodBoolean>; enableHealth: ZodDefault<ZodOptional<ZodBoolean>>; healthFunction: ZodOptional<ZodAny>; healthPath: ZodDefault<ZodOptional<ZodString>>; ... }, $strip>` — Runtime configuration schema for the Hono HTTP service.
- `const honoV1Service: ServiceBuilder<SetNewTypeValue<SetNewTypeValues<ServiceBuilderTypes, { ConfigInputType: { apiMountPath: unknown; autoRegisterServicesFromConfig: unknown; enableDynamicRoutes: unknown; enableHealth: unknown; healthFunction: unknown; healthPath: unknown; ... }; ConfigType: { apiMountPath: unknown; autoRegisterServicesFromConfig: unknown; enableDynamicRoutes: unknown; enableHealth: unknown; healthFunction: unknown; healthPath: unknown; ... }; ServiceClassType: Service<unknown> }>, "ServiceClassType", HonoServiceClass<EmptyObject, VariablesBase>>>` — Built-in Hono HTTP service definition.
- `const honoV1ServiceBuilder: ServiceBuilder<SetNewTypeValue<SetNewTypeValues<ServiceBuilderTypes, { ConfigInputType: { apiMountPath: unknown; autoRegisterServicesFromConfig: unknown; enableDynamicRoutes: unknown; enableHealth: unknown; healthFunction: unknown; healthPath: unknown; ... }; ConfigType: { apiMountPath: unknown; autoRegisterServicesFromConfig: unknown; enableDynamicRoutes: unknown; enableHealth: unknown; healthFunction: unknown; healthPath: unknown; ... }; ServiceClassType: Service<unknown> }>, "ServiceClassType", HonoServiceClass<EmptyObject, VariablesBase>>>` — Builder for the built-in Hono HTTP service.
- `const honoV1ServiceCommandsToRestApiInputPayloadSchema: ZodRecord<ZodString, ZodUnknown>` — Schema for dynamic endpoint metadata received from service definition info messages.
- `const InfoObjectSchema: ZodObject<{ contact: ZodOptional<ZodObject<{ email: unknown; name: unknown; url: unknown }, $strip>>; description: ZodDefault<ZodString>; license: ZodOptional<ZodObject<{ name: unknown; url: unknown }, $strip>>; termsOfService: ZodOptional<ZodString>; title: ZodDefault<ZodString>; version: ZodDefault<ZodString> }, $strip>` — Schema for the OpenAPI info object.
- `const OPENAPI_DEFAULT_INFO: { description: string; title: string; version: string }` — Default OpenAPI info block used when no application-specific metadata is supplied.
- `const ProblemDetailsObjectSchema: ZodObject<{ typeBaseUri: ZodOptional<ZodString> }, $strip>` — Schema for RFC 9457 problem details configuration.
- `const puristaVersion: "3.0.1"` — The PURISTA package version embedded in the published runtime build.
- `const ServerObjectSchema: ZodObject<{ description: ZodOptional<ZodString>; url: ZodString; variables: ZodOptional<ZodAny> }, $strip>` — Schema for OpenAPI server objects.
- `const serviceCommandsToRestApiSubscriptionBuilder: SubscriptionDefinitionBuilder<HonoServiceClass<EmptyObject, VariablesBase>, SubscriptionDefinitionBuilderTypes<ZodRecord<ZodString, ZodUnknown>, any, any, any, any, any, EmptyObject, InvokeList, StreamInvokeList, Record<string, Schema>>>` — Subscription builder that dynamically adds HTTP endpoints for newly announced commands.
- `const ServiceEvent: object` — Reserved service event map for the Hono HTTP service.
- `const TagObjectSchema: ZodObject<{ description: ZodOptional<ZodString>; externalDocs: ZodOptional<ZodObject<{ description: unknown; url: unknown }, $strip>>; name: ZodString }, $strip>` — Schema for OpenAPI tag objects.

### Functions

- `addPathToOpenApi(openApiBuilder: OpenApiBuilder, metadata: { expose: { contentEncodingRequest: string; contentEncodingResponse: string; contentTypeRequest: string; contentTypeResponse: string; deprecated: boolean; inputPayload: SchemaObject; ... } & { http: { method: unknown | unknown | unknown | unknown | unknown; mode: unknown | unknown; openApi: { additionalStatusCodes: unknown; description: unknown; isSecure: unknown; operationId: unknown; query: unknown; summary: unknown; ... }; path: string; stream: { documentationUrl: unknown; mode: unknown; protocol: unknown } } } }, path: string, config: Config, owner?: PuristaOpenApiOperationOwner): void`
- `collectAggregateStreamResult(handle: StreamHandle): Promise<{ payload: { data: unknown; isHandledError: unknown; message: unknown; status: unknown; traceId: unknown } & { message: unknown; status: unknown }; status: "error"; statusCode: StatusCode | ContentfulStatusCode } | { payload: object | null; status: "success"; statusCode: ContentfulStatusCode }>`
- `encodeProtocolSseEvent(encoder: TextEncoder, event: ProtocolSseEvent): Uint8Array`
- `getErrorName(code: StatusCode): string`
- `getErrorResponseSchema(code: StatusCode, message: string, schema?: SchemaObject, problemTypeConfig?: ProblemTypeConfig): SchemaObject`
- `getParameterDefinition(path: string, parameterschema?: SchemaObject): ParameterObject[]`
- `getProblemDetailsSchema(code: StatusCode, message: string, schema?: SchemaObject, problemTypeConfig?: ProblemTypeConfig): SchemaObject`
- `getProblemTypeUri(status: number, data?: unknown, config?: ProblemTypeConfig): string`
- `getQueryDefinition(queryDefinition: QueryParameter<Record<string, unknown>>[] | undefined, parameterschema?: SchemaObject): ParameterObject[]`
- `isProtocolSseEvent(value: unknown): value`
- `isStreamErrorPayload(payload: StreamTransportFramePayload): payload`
- `isTransportControlFrame(frameType: unknown): boolean`
- `negotiateProblemRepresentation(acceptHeader?: string): "json" | "markdown"`
- `renderProblemDetailsMarkdown(problem: ProblemDetails): string`
- `resolveHttpStreamingMode(input: { explicitMode: "stream" | "aggregate"; isDeclaredStreamDefinition: boolean; responseContentType: string }): "stream" | "aggregate"`
- `toProblemDetails(error: unknown, input: { instance: string; problemTypeConfig: ProblemTypeConfig; safeInternalDetails: boolean; statusCode: number; traceId: string }): ProblemDetails`