# HonoServiceClass API

PURISTA service that exposes command, stream and async queue-backed endpoints through Hono.

---
Canonical: /handbook/api/classes/_purista_hono-http-server.HonoServiceClass/
Source: hono-http-server/src/service/hono/v1/HonoServiceClass.ts
Format: Markdown for agents
---

PURISTA service that exposes command, stream and async queue-backed endpoints through Hono.

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

## Signature

```typescript
class HonoServiceClass<Bindings, Variables>
```

## 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

### Constructors

- `new constructor<Bindings, Variables>(config: ServiceConstructorInput<ServiceClassTypes<{ apiMountPath: string; autoRegisterServicesFromConfig: boolean; enableDynamicRoutes: boolean; enableHealth: boolean; healthFunction: any; healthPath: string; ... }, EmptyObject>>)` — Creates the Hono service runtime and configures routing, health, and protection defaults.

### Properties

- `__serviceClassTypes: ServiceClassTypes<{ apiMountPath: string; autoRegisterServicesFromConfig: boolean; enableDynamicRoutes: boolean; enableHealth: boolean; healthFunction: any; healthPath: string; ... }>` — Type-only anchor used to preserve cascading service builder types.
- `activeStreamSessions: Map<string, { cancelled: boolean; cancelReason: string; onCancel: (reason?: string) => void[] }>`
- `app: Hono<{ Bindings: Bindings; Variables: Variables }, BlankSchema, "/">` — Hono application hosting health, OpenAPI and generated endpoint routes.
- `commandDefinitionList: CommandDefinitionListResolved<any>`
- `commands: Map<string, CommandDefinition<any, any, any, any, any, any, any, any, any, any, EmptyObject, any, any, any>>`
- `config: { apiMountPath: string; autoRegisterServicesFromConfig: boolean; enableDynamicRoutes: boolean; enableHealth: boolean; healthFunction: any; healthPath: string; ... }`
- `configSchema: Schema | undefined`
- `configStore: ConfigStore`
- `eventBridge: EventBridge`
- `info: ServiceInfoType`
- `isStarted: boolean`
- `logger: Logger`
- `metricContext: PuristaMetricContext<PuristaMetricDefinitions>`
- `metricDefinitions: PuristaMetricDefinitions`
- `metricsRecorder: PuristaMetricsRecorder`
- `openApi: OpenApiBuilder` — OpenAPI builder populated as command and stream endpoints are registered.
- `queueDefinitionList: QueueDefinitionListResolved<any>`
- `queueWorkerDefinitionList: QueueWorkerDefinitionListResolved<any>`
- `resources: EmptyObject`
- `secretStore: SecretStore`
- `spanProcessor: SpanProcessor | undefined`
- `stateStore: StateStore`
- `streamDefinitionList: StreamDefinitionListResolved<any>`
- `streams: Map<string, StreamDefinition<any, any, any, any, any, any, any, EmptyObject, any, any, any>>`
- `subscriptionDefinitionList: SubscriptionDefinitionListResolved<any>`
- `subscriptions: Map<string, SubscriptionDefinition<any, any, any, any, any, any, any, any, EmptyObject, any, any, any>>`
- `traceProvider: NodeTracerProvider`

### Accessors

- `name`
- `serviceInfo`

### Methods

- `addEndpoint(metadata: CommandDefinitionMetadataBase, service: EBMessageAddress): void` — Adds a single command or stream endpoint to the Hono router.
- `destroy(): Promise<void>` — Stop and destroy the current service
- `executeCommand(message: Readonly<Command>): Promise<Readonly<Omit<{ contentEncoding: unknown; contentType: unknown; correlationId: unknown; eventName: unknown; id: unknown; isHandledError: unknown; ... }, "instanceId">> | { contentEncoding: string; contentType: string; correlationId: string; eventName: string; id: string; messageType: CommandSuccessResponse; ... }>` — Called when a command is received by the service
- `executeStream(message: Readonly<StreamMessage>): Promise<void>`
- `executeSubscription(message: Readonly<EBMessage>, subscriptionName: string): Promise<Omit<{ contentEncoding: string; contentType: string; correlationId: string; eventName: string; id: string; messageType: CustomMessage; ... }, "id" | "timestamp"> | undefined>`
- `getConsumeStreamFunction<StreamInvokes>(serviceTarget: string, traceId?: string, principalId?: string, tenantId?: string, streamInvokes?: StreamInvokes): OpenStreamFunction`
- `getContextFunctions(logger: Logger, queueNamespace?: QueueContext): ContextBase`
- `getEmitFunction<EmitList>(serviceTarget: string, traceId?: string, principalId?: string, tenantId?: string, emitList?: EmitList): (eventName: K, eventPayload?: Payload, contentType?: string, contentEncoding?: string) => Promise<void>`
- `getInFlightDiagnostics(): InFlightDiagnostics`
- `getInvokeFunction<Invokes>(serviceTarget: string, traceId?: string, principalId?: string, tenantId?: string, invokes?: Invokes): (receiver: EBMessageAddress, invokePayload: Payload, invokeparameter: Parameter, contentType?: string, contentEncoding?: string) => Promise<any>`
- `getPausedSubscriptionConsumerState(): PausedSubscriptionConsumersByRegistrationKey`
- `getQueueNamespace(queueInvokes?: QueueInvokeList, traceId?: string, principalId?: string, tenantId?: string): { enqueue: QueueInvokeFunction & QueueInvokeClientMap<QueueInvokeList>; scheduleAt: QueueScheduleFunction & QueueScheduleProxy<QueueInvokeClientMap<QueueInvokeList>> }`
- `getQueueWorkerPauseState(): QueueWorkerPauseStateByQueue`
- `getServiceHealth(): Promise<ServiceHealthState>`
- `getTracer(name?: string, version?: string): Tracer` — Returns open telemetry tracer of this service
- `initializeEventbridgeConnect(commandDefinitionList: CommandDefinitionListResolved<any>, subscriptions: SubscriptionDefinitionListResolved<any>, streams: StreamDefinitionListResolved<any>): Promise<void>` — Connect service to event bridge to receive commands and command responses
- `initializeQueues(): Promise<void>`
- `invoke<T>(input: Omit<Command, "id" | "messageType" | "timestamp" | "correlationId" | "sender">, endpoint: string): Promise<T>` — Invokes a PURISTA command through the event bridge on behalf of an HTTP endpoint.
- `openStream(input: Omit<Command, "id" | "messageType" | "timestamp" | "correlationId" | "sender">, endpoint: string, timeoutMs: number): Promise<StreamHandle<unknown, unknown>>` — Opens a PURISTA stream through the event bridge on behalf of an HTTP endpoint.
- `pauseQueueWorkers(queueName: string, reason?: string): void`
- `prepareDestroy(): { destroy: () => Promise<void>; name: string }` — Helper function to be used in gracefulShutdown.
It prevents to handle new requests during shut down.
Incoming requests are rejected with 503 Service Unavailable.
- `registerCommand(commandDefinition: CommandDefinition<any, any, any, any, any, any, any, any, any, any, EmptyObject, any, any, any>): Promise<void>`
- `registerService(...services: AnyService[]): HonoServiceClass<Bindings, Variables>` — Registers service instances and adds their HTTP-exposed commands and streams.
- `registerStream(streamDefinition: StreamDefinition<any, any, any, any, any, any, any, EmptyObject, any, any, any>): Promise<void>`
- `registerSubscription(subscriptionDefinition: SubscriptionDefinition<any, any, any, any, any, any, any, any, EmptyObject, any, any, any>): Promise<void>`
- `resumeQueueWorkers(queueName: string): void`
- `resumeSubscriptionConsumer(registrationKey: string): Promise<void>`
- `sendServiceInfo(infoType: InfoMessageType, target?: string, payload?: Record<string, unknown>): Promise<Readonly<EBMessage>>` — Broadcast service info message
- `setHealthFunction(fn: HealthFunction<HonoServiceClass<Bindings, Variables>>): HonoServiceClass<Bindings, Variables>` — Sets the callback used by the configured health endpoint.
- `setHonoTypes<E>(): HonoServiceClass<Bindings & E["Bindings"], Variables & E["Variables"]>` — Narrows Hono `Bindings` and `Variables` types for middleware and handlers.
- `setProtectMiddleware(fn: EndpointProtectMiddleware<HonoServiceClass<Bindings, Variables>, Bindings, Variables>): HonoServiceClass<Bindings, Variables>` — Sets middleware for endpoints marked as protected in HTTP metadata.
- `setServiceAvailable(): Promise<void>` — Set the service available
Request will be processed.
- `setServiceUnavailable(): Promise<void>` — Set the service unavailable
The webserver will return 503 Service Unavailable
- `start(): Promise<void>` — Starts the service and registers health, OpenAPI and error handling routes.
- `startActiveSpan<F>(name: string, opts: SpanOptions, context: Context | undefined, fn: (span: Span) => Promise<F>): Promise<F>` — Start a child span for opentelemetry tracking
- `startQueueWorkers(): void`
- `stopQueueWorkers(): Promise<void>`
- `wrapInSpan<F>(name: string, opts: SpanOptions, fn: (span: Span) => Promise<F>, context?: Context): Promise<F>` — Start span for opentelemetry tracking on same level.
The created span will not become the "active" span within opentelemetry!