kite-x402-hono 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +1 -0
- package/CHANGELOG.md +14 -0
- package/README.md +19 -1
- package/README.zh-CN.md +13 -0
- package/dist/app.js +10 -1
- package/dist/cli.js +1 -1
- package/dist/config.d.ts +1 -0
- package/dist/config.js +1 -0
- package/docs/week-3.md +38 -0
- package/package.json +1 -1
package/.env.example
CHANGED
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
- Add `FACILITATOR_TIMEOUT_MS` (default 90000, range 1–300000) and validate
|
|
6
|
+
environment and programmatic configuration while preserving older Config objects.
|
|
7
|
+
- Apply the official SDK HTTP abort mechanism to facilitator capability discovery,
|
|
8
|
+
payment verification and settlement, including response headers and bodies.
|
|
9
|
+
- Add seven real HTTP timeout tests covering failure responses, concurrency-slot
|
|
10
|
+
recovery, health availability and absence of automatic payment retries.
|
|
11
|
+
- Update English/Chinese documentation, CLI help and the environment example.
|
|
12
|
+
|
|
13
|
+
The timeout applies per HTTP attempt; SDK initialization backoff may extend the
|
|
14
|
+
whole request. Custom facilitator clients manage their own deadlines. Settlement
|
|
15
|
+
timeout leaves the payment outcome unknown and does not guarantee no charge.
|
|
16
|
+
|
|
3
17
|
## 0.2.0
|
|
4
18
|
|
|
5
19
|
- Bound the complete payment lifecycle with `MAX_CONCURRENT_REQUESTS` (default
|
package/README.md
CHANGED
|
@@ -125,7 +125,7 @@ Compatibility notes:
|
|
|
125
125
|
error response is not proof of no charge. Reconcile before retrying a payment.
|
|
126
126
|
- `/healthz` is process liveness, not proof of upstream/facilitator readiness.
|
|
127
127
|
- The CLI disables Bun's short idle timeout so it does not disconnect a client
|
|
128
|
-
during settlement. SDK facilitator calls
|
|
128
|
+
during settlement. SDK facilitator calls default to a configurable 90-second timeout;
|
|
129
129
|
deploy behind a reverse proxy with suitable request deadlines and rate limits.
|
|
130
130
|
|
|
131
131
|
## Verification
|
|
@@ -146,6 +146,24 @@ for upstream capacity and response sizes; use edge rate limits for hostile traff
|
|
|
146
146
|
Do not treat every 503 as safe to retry: only this wrapper's `service_busy`
|
|
147
147
|
response denotes pre-payment rejection. Settlement errors still need reconciliation.
|
|
148
148
|
|
|
149
|
+
### Facilitator deadlines (added in 0.3.0)
|
|
150
|
+
|
|
151
|
+
`FACILITATOR_TIMEOUT_MS` accepts integers from 1 to 300000, default 90000.
|
|
152
|
+
It configures the official SDK HTTP client's timeout for each `/supported`,
|
|
153
|
+
`/verify` and `/settle` attempt, including response-body consumption. This is
|
|
154
|
+
separate from `UPSTREAM_TIMEOUT_MS`; it is not a total request deadline. The SDK
|
|
155
|
+
may retry `/supported` on HTTP 429 with backoff, so initialization can take longer.
|
|
156
|
+
Custom injected facilitators own their own cancellation and timeout policy.
|
|
157
|
+
|
|
158
|
+
An initialization timeout returns 503 `facilitator_unavailable`. Verification
|
|
159
|
+
and settlement timeouts return SDK 502 errors. Verification timeout does not call
|
|
160
|
+
the upstream or settle. Settlement timeout withholds the protected response, but
|
|
161
|
+
the upstream already ran and the facilitator may have completed the charge.
|
|
162
|
+
There is no automatic retry of verification or settlement. Reconcile an unknown
|
|
163
|
+
settlement before retrying. Slots are released when requests finish, and health
|
|
164
|
+
checks remain available. Lowering the timeout increases indeterminate outcomes
|
|
165
|
+
for slow settlements; choose a deadline suitable for your deployment.
|
|
166
|
+
|
|
149
167
|
### Commands
|
|
150
168
|
|
|
151
169
|
```sh
|
package/README.zh-CN.md
CHANGED
|
@@ -123,6 +123,19 @@ Bun.serve({ port: config.port, fetch: app.fetch });
|
|
|
123
123
|
恶意流量仍应通过入口限流控制。不能把所有 503 都当成可安全重试:只有本代理的
|
|
124
124
|
`service_busy` 表示付款前拒绝;结算错误仍需先核对结果。
|
|
125
125
|
|
|
126
|
+
### Facilitator 超时(0.3.0 新增)
|
|
127
|
+
|
|
128
|
+
`FACILITATOR_TIMEOUT_MS` 默认 90000 毫秒,允许 1 至 300000 的整数。
|
|
129
|
+
使用官方 SDK 的 HTTP 取消机制,对 `/supported`、`/verify`、`/settle` 的每次请求
|
|
130
|
+
限制等待时间,覆盖响应头和响应体。它独立于上游 API 的 `UPSTREAM_TIMEOUT_MS`,
|
|
131
|
+
不是整个付费请求的总时限;SDK 对 `/supported` 的 429 响应可能退避重试。
|
|
132
|
+
自行注入的 facilitator 需要自行实现超时及取消策略。
|
|
133
|
+
|
|
134
|
+
初始化超时返回 503 `facilitator_unavailable`;付款验证及结算超时返回 SDK 的 502。
|
|
135
|
+
验证超时不会调用上游或结算。结算超时不返回受保护内容,但上游已经执行,链上可能已经扣款。
|
|
136
|
+
不自动重试验证和结算;结果不明时先核对再重试。请求结束后释放并发名额,健康检查保持可用。
|
|
137
|
+
超时设得过短会增加结算结果不明的情况,应按实际部署选择。
|
|
138
|
+
|
|
126
139
|
### 检查命令
|
|
127
140
|
|
|
128
141
|
```sh
|
package/dist/app.js
CHANGED
|
@@ -7,6 +7,12 @@ import { parsePrice } from "./networks.js";
|
|
|
7
7
|
import { proxy } from "./proxy.js";
|
|
8
8
|
export function createApp(config = loadConfig(), options = {}) {
|
|
9
9
|
const app = new Hono();
|
|
10
|
+
const facilitatorTimeoutMs = config.facilitatorTimeoutMs ?? 90000;
|
|
11
|
+
if (!Number.isInteger(facilitatorTimeoutMs) ||
|
|
12
|
+
facilitatorTimeoutMs < 1 ||
|
|
13
|
+
facilitatorTimeoutMs > 300000) {
|
|
14
|
+
throw new Error("facilitatorTimeoutMs must be an integer between 1 and 300000");
|
|
15
|
+
}
|
|
10
16
|
const capacity = config.maxConcurrentRequests ?? 64;
|
|
11
17
|
if (!Number.isInteger(capacity) || capacity < 1 || capacity > 10000) {
|
|
12
18
|
throw new Error("maxConcurrentRequests must be an integer between 1 and 10000");
|
|
@@ -29,7 +35,10 @@ export function createApp(config = loadConfig(), options = {}) {
|
|
|
29
35
|
}
|
|
30
36
|
});
|
|
31
37
|
const facilitator = options.facilitator ??
|
|
32
|
-
new HTTPFacilitatorClient({
|
|
38
|
+
new HTTPFacilitatorClient({
|
|
39
|
+
url: config.facilitatorUrl,
|
|
40
|
+
timeoutMs: facilitatorTimeoutMs,
|
|
41
|
+
});
|
|
33
42
|
const server = new x402ResourceServer(facilitator).register(config.chain.network, new ExactEvmScheme());
|
|
34
43
|
const httpServer = new x402HTTPResourceServer(server, {
|
|
35
44
|
"/v1/*": {
|
package/dist/cli.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
import { createApp } from "./app.js";
|
|
3
3
|
import { loadConfig } from "./config.js";
|
|
4
4
|
if (process.argv.includes("--help")) {
|
|
5
|
-
console.log("Usage: kite-x402-hono\nRequired: PAY_TO, UPSTREAM_URL\nOptional: KITE_NETWORK, PRICE_USD, PORT, FACILITATOR_URL, UPSTREAM_AUTH_HEADER, UPSTREAM_AUTH_VALUE, UPSTREAM_TIMEOUT_MS, MAX_BODY_BYTES, MAX_CONCURRENT_REQUESTS\nSee README.md for configuration and examples.");
|
|
5
|
+
console.log("Usage: kite-x402-hono\nRequired: PAY_TO, UPSTREAM_URL\nOptional: KITE_NETWORK, PRICE_USD, PORT, FACILITATOR_URL, UPSTREAM_AUTH_HEADER, UPSTREAM_AUTH_VALUE, UPSTREAM_TIMEOUT_MS, MAX_BODY_BYTES, MAX_CONCURRENT_REQUESTS, FACILITATOR_TIMEOUT_MS\nSee README.md for configuration and examples.");
|
|
6
6
|
}
|
|
7
7
|
else {
|
|
8
8
|
try {
|
package/dist/config.d.ts
CHANGED
package/dist/config.js
CHANGED
|
@@ -79,5 +79,6 @@ export function loadConfig(env = process.env) {
|
|
|
79
79
|
timeoutMs: integer(get("UPSTREAM_TIMEOUT_MS", "10000"), "UPSTREAM_TIMEOUT_MS", 120000),
|
|
80
80
|
maxBodyBytes: integer(get("MAX_BODY_BYTES", "1048576"), "MAX_BODY_BYTES", 16777216),
|
|
81
81
|
maxConcurrentRequests: integer(get("MAX_CONCURRENT_REQUESTS", "64"), "MAX_CONCURRENT_REQUESTS", 10000),
|
|
82
|
+
facilitatorTimeoutMs: integer(get("FACILITATOR_TIMEOUT_MS", "90000"), "FACILITATOR_TIMEOUT_MS", 300000),
|
|
82
83
|
};
|
|
83
84
|
}
|
package/docs/week-3.md
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Week 3: configurable facilitator deadlines
|
|
2
|
+
|
|
3
|
+
Continue the original `x402-wrapper` repository. Version 0.2.0 exposed upstream
|
|
4
|
+
timeouts but left facilitator HTTP calls at the SDK's fixed 90-second default.
|
|
5
|
+
Slow verification/settlement can hold the bounded concurrency slots for too long.
|
|
6
|
+
|
|
7
|
+
## Implementation
|
|
8
|
+
|
|
9
|
+
- Add `FACILITATOR_TIMEOUT_MS` (default 90000, range 1–300000).
|
|
10
|
+
- Pass the deadline into the official SDK HTTPFacilitatorClient; use its real
|
|
11
|
+
HTTP abort mechanism, not a Promise.race that leaves requests running.
|
|
12
|
+
- Validate environment and programmatic configuration; old Config objects retain
|
|
13
|
+
the default through an optional field.
|
|
14
|
+
- Update CLI help, environment example and both READMEs with per-attempt semantics,
|
|
15
|
+
custom-client boundaries, 429 initialization backoff and settlement uncertainty.
|
|
16
|
+
|
|
17
|
+
## Evidence
|
|
18
|
+
|
|
19
|
+
Seven new tests use real local HTTP with the SDK client, not a fake timeout error.
|
|
20
|
+
For each of supported/verify/settle they stall either response headers or the body.
|
|
21
|
+
They verify failure status, absence of protected output, no false payment receipt,
|
|
22
|
+
no automatic payment retry, expected upstream call count, health availability and
|
|
23
|
+
concurrency-slot recovery. Initialization can recover on the next unpaid request.
|
|
24
|
+
Config tests cover bounds and backwards compatibility.
|
|
25
|
+
|
|
26
|
+
Settlement timeout is not a no-charge guarantee. The upstream has run and a
|
|
27
|
+
facilitator may settle after the connection is aborted. Tests deliberately probe
|
|
28
|
+
recovery with unpaid requests rather than replaying a payment. These source tests do not perform real chain transactions. The functionality is
|
|
29
|
+
included in version 0.3.0; npm publication is verified separately from source tests.
|
|
30
|
+
|
|
31
|
+
## 可提交说明
|
|
32
|
+
|
|
33
|
+
第三周新增 FACILITATOR_TIMEOUT_MS 配置,接入官方 x402 SDK 的 HTTP 请求取消机制,
|
|
34
|
+
分别限制能力查询、付款验证和结算的响应等待时间,覆盖响应头与响应体。
|
|
35
|
+
保持默认 90 秒及旧配置兼容,新增参数校验、CLI 帮助和中英文说明。
|
|
36
|
+
新增真实本地 HTTP 故障测试,验证三个阶段的响应头/响应体停滞、付款前不调用上游、
|
|
37
|
+
结算超时不返回受保护内容、不自动重试付款,以及并发名额释放和健康检查可用性。
|
|
38
|
+
结算超时按结果未知处理,不宣称一定未扣款;测试不涉及真实链上付款。
|