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

registerFunction(id, handler)

registerTrigger({ config: { middleware_function_ids } })

{ action: 'continue' }

{ action: 'respond', response: { status_code, body } }

req.request.headers

req.context

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.