iii-http-middleware

Original：🇺🇸 English

Translated

Registers engine-level middleware functions that run before HTTP handlers. Use when adding authentication, request logging, rate limiting, or any pre-handler logic to HTTP endpoints.

2installs

Sourceiii-hq/iii

Added on2026-05-13

NPX Install

npx skill4agent add iii-hq/iii iii-http-middleware

SKILL.md Content

View Translation Comparison →

HTTP Middleware

Comparable to: Express middleware, Fastify hooks, Django middleware

Key Concepts

Use the concepts below when they fit the task. Not every middleware setup needs all of them.

Middleware functions are registered like normal functions but return
```
{ action: 'continue' }
```
or
```
{ action: 'respond', response }
```
instead of a normal response
Middleware is attached to HTTP triggers via
```
middleware_function_ids
```
in the trigger config
The engine executes middleware in order — first middleware runs first, then the next, then the handler
Middleware receives a
```
MiddlewareFunctionInput
```
with
```
phase
```
,
```
request
```
(path_params, query_params, headers, method), and
```
context
```
from auth
Returning
```
{ action: 'respond' }
```
short-circuits the chain — the handler never runs
Returning
```
{ action: 'continue' }
```
passes to the next middleware or the handler

Architecture

HTTP request
  → iii-http (port 3111)
    → Middleware 1 (continue / respond)
      → Middleware 2 (continue / respond)
        → registerFunction handler
          → { status_code, body, headers } response

iii Primitives Used

Primitive	Purpose
`registerFunction(id, handler)`	Define a middleware function
`registerTrigger({ config: { middleware_function_ids } })`	Attach middleware to an HTTP trigger
`{ action: 'continue' }`	Pass to next middleware or handler
`{ action: 'respond', response: { status_code, body } }`	Short-circuit and return response immediately
`req.request.headers`	Access request headers in middleware
`req.context`	Access auth context from RBAC auth function

Reference Implementation

See ../references/http-middleware.js for the full working example — auth and logging middleware protecting HTTP endpoints.

Common Patterns

Code using this pattern commonly includes, when relevant:

iii.registerFunction('middleware::auth', async (req) => { ... })

— auth middleware checking headers

iii.registerFunction('middleware::rate-limit', async (req) => { ... })

— rate limiting middleware

iii.registerFunction('middleware::request-logger', async (req) => { ... })

— request logging

```
req.request?.headers?.authorization
```
— reading auth tokens

return { action: 'respond', response: { status_code: 401, body: { error: 'Unauthorized' } } }

— reject request

```
return { action: 'continue' }
```
— allow request through

config: { middleware_function_ids: ['middleware::auth', 'middleware::logger'] }

— attach to trigger

Adapting This Pattern

Use the adaptations below when they apply to the task.

Chain multiple middleware for layered concerns (logging before auth before rate-limiting)
Use middleware for cross-cutting concerns shared across multiple endpoints
Combine with RBAC auth functions for role-based access control — auth context flows to middleware via
```
req.context
```
Keep middleware functions focused on one concern each for reusability

Pattern Boundaries

If the task is just exposing HTTP endpoints without middleware, prefer
```
iii-http-endpoints
```
.
If auth needs are complex (RBAC with function discovery control), combine this with RBAC worker auth functions.
Stay with
```
iii-http-middleware
```
when the primary need is pre-handler processing for HTTP routes.

When to Use

Use this skill when the task is primarily about
```
iii-http-middleware
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.