PolicyDefinition

Defined in: src/policies/sdk/define-policy.ts:60

Declarative policy definition passed to definePolicy.

Type Parameters

TConfig

TConfig extends PolicyConfig = PolicyConfig

Properties

defaults?

optional defaults: Partial<TConfig>

Defined in: src/policies/sdk/define-policy.ts:66

Default values for optional config fields.

---

evaluate?

optional evaluate: object

Defined in: src/policies/sdk/define-policy.ts:114

Protocol-agnostic evaluator for multi-runtime policies.

Used by non-HTTP runtimes (ext_proc, WebSocket). The HTTP runtime uses handler and ignores this field.

Implement this alongside handler to make a policy work across all runtimes. The config is pre-merged and injected into PolicyEvalHandlerContext.

onRequest()?

optional onRequest: (input, ctx) => Promise<PolicyResult>

Parameters

input

PolicyInput

ctx

PolicyEvalHandlerContext<TConfig>

Returns

Promise<PolicyResult>

onResponse()?

optional onResponse: (input, ctx) => Promise<PolicyResult>

Parameters

input

PolicyInput

ctx

PolicyEvalHandlerContext<TConfig>

Returns

Promise<PolicyResult>

Example

const myPolicy = definePolicy<MyConfig>({
  name: "my-policy",
  priority: Priority.AUTH,
  phases: ["request-headers"],
  handler: async (c, next, { config }) => { ... },
  evaluate: {
    onRequest: async (input, { config }) => {
      const token = input.headers.get("authorization");
      if (!token) return { action: "reject", status: 401, code: "unauthorized", message: "Missing" };
      return { action: "continue" };
    },
  },
});

---

handler()

handler: (c, next, ctx) => void | Promise<void>

Defined in: src/policies/sdk/define-policy.ts:81

The HTTP policy handler. Receives the Hono context, next, and a PolicyHandlerContext with config, debug, and gateway context.

Used by the HTTP runtime (createGateway).

Parameters

c

Context

next

Next

ctx

PolicyHandlerContext<TConfig>

Returns

void | Promise<void>

---

httpOnly?

optional httpOnly: true

Defined in: src/policies/sdk/define-policy.ts:145

Set to true for policies that only work with the HTTP protocol.

These policies rely on HTTP-specific concepts (Request/Response objects, specific headers, HTTP status codes, etc.) and cannot be meaningfully evaluated in other protocols like ext_proc or WebSocket.

When set, this is passed through to the returned Policy’s httpOnly property.

---

name

name: string

Defined in: src/policies/sdk/define-policy.ts:62

Unique policy name (e.g. "my-auth", "custom-cache").

---

phases?

optional phases: ProcessingPhase[]

Defined in: src/policies/sdk/define-policy.ts:134

Processing phases this policy participates in.

Used by phase-based runtimes (ext_proc) to skip policies that don’t apply to the current phase. Passed through to the returned Policy.phases.

Default: ["request-headers"].

---

priority?

optional priority: number

Defined in: src/policies/sdk/define-policy.ts:64

Execution priority. Use Priority constants. Default: Priority.DEFAULT (100).

---

validate()?

optional validate: (config) => void

Defined in: src/policies/sdk/define-policy.ts:74

Optional construction-time config validation.

Called once when the factory is invoked (before any requests). Throw a GatewayError to reject invalid config eagerly rather than failing on the first request.

Parameters

config

TConfig

Returns

void