iii-http-middleware

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTTP Middleware

HTTP 中间件

Comparable to: Express middleware, Fastify hooks, Django middleware

可类比：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

当任务需要时使用以下概念，并非所有中间件配置都需要用到全部内容。

中间件函数的注册方式与普通函数相同，但返回
```
{ action: 'continue' }
```
或
```
{ action: 'respond', response }
```
而非普通响应
通过触发器配置中的
```
middleware_function_ids
```
将中间件附加到HTTP触发器
引擎会按顺序执行中间件——第一个中间件先运行，接着是下一个，最后才是处理器
中间件会接收包含
```
phase
```
、
```
request
```
（path_params、query_params、headers、method）以及来自认证的
```
context
```
的
```
MiddlewareFunctionInput
```
返回
```
{ action: 'respond' }
```
会中断调用链——处理器将不会运行
返回
```
{ action: 'continue' }
```
会将请求传递给下一个中间件或处理器

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

使用的 iii 原语

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

原语	用途
`registerFunction(id, handler)`	定义中间件函数
`registerTrigger({ config: { middleware_function_ids } })`	将中间件附加到HTTP触发器
`{ action: 'continue' }`	将请求传递给下一个中间件或处理器
`{ action: 'respond', response: { status_code, body } }`	中断调用链并立即返回响应
`req.request.headers`	在中间件中访问请求头
`req.context`	从RBAC认证函数中访问认证上下文

Reference Implementation

参考实现

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

完整可运行示例请查看 ../references/http-middleware.js —— 用于保护HTTP端点的认证和日志中间件。

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

使用该模式的代码通常会包含以下相关内容：

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

—— 检查请求头的认证中间件

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

—— 限流中间件

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

—— 请求日志中间件

```
req.request?.headers?.authorization
```
—— 读取认证令牌

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

—— 拒绝请求

```
return { action: 'continue' }
```
—— 允许请求通过

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

—— 附加到触发器

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

当任务适用时，可采用以下适配方式：

串联多个中间件以实现分层处理（日志→认证→限流）
将中间件用于多个端点共享的横切关注点
与RBAC认证函数结合实现基于角色的访问控制——认证上下文通过
```
req.context
```
传递给中间件
每个中间件函数专注于单一关注点以提升可复用性

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.

如果任务仅需暴露HTTP端点而无需中间件，优先使用
```
iii-http-endpoints
```
。
如果认证需求复杂（包含函数发现控制的RBAC），可将此模式与RBAC worker认证函数结合使用。
当主要需求是为HTTP路由提供处理器前置处理时，使用
```
iii-http-middleware
```
。

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.

当任务主要涉及 iii 引擎中的
```
iii-http-middleware
```
时，使用该技能。
当请求直接要求该模式或等效实现时触发。

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.

切勿将该技能作为无关任务的通用 fallback。
当更具体的 iii 技能更合适时，不得使用该技能。
在应用该技能的示例之前，务必验证环境和安全约束。