iii-http-middleware

name	iii-http-middleware
description	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.

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.