kite-x402-hono 0.2.0 → 0.3.1
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 +22 -0
- package/README.md +29 -1
- package/README.zh-CN.md +21 -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/dist/proxy.js +12 -3
- package/docs/week-3.md +38 -0
- package/docs/week-4.md +38 -0
- package/package.json +1 -1
package/.env.example
CHANGED
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.1
|
|
4
|
+
|
|
5
|
+
- Make rejected-body and redirect stream cleanup non-blocking so stalled producer
|
|
6
|
+
cancellation cannot retain a request slot. Preserve original errors when cleanup fails.
|
|
7
|
+
- Cancel unfinished reads, including already-aborted requests, and release reader locks.
|
|
8
|
+
- Add nine regression tests for stalled/rejected cleanup, capacity recovery, aborts
|
|
9
|
+
and byte-preserving successful reads.
|
|
10
|
+
|
|
11
|
+
## 0.3.0
|
|
12
|
+
|
|
13
|
+
- Add `FACILITATOR_TIMEOUT_MS` (default 90000, range 1–300000) and validate
|
|
14
|
+
environment and programmatic configuration while preserving older Config objects.
|
|
15
|
+
- Apply the official SDK HTTP abort mechanism to facilitator capability discovery,
|
|
16
|
+
payment verification and settlement, including response headers and bodies.
|
|
17
|
+
- Add seven real HTTP timeout tests covering failure responses, concurrency-slot
|
|
18
|
+
recovery, health availability and absence of automatic payment retries.
|
|
19
|
+
- Update English/Chinese documentation, CLI help and the environment example.
|
|
20
|
+
|
|
21
|
+
The timeout applies per HTTP attempt; SDK initialization backoff may extend the
|
|
22
|
+
whole request. Custom facilitator clients manage their own deadlines. Settlement
|
|
23
|
+
timeout leaves the payment outcome unknown and does not guarantee no charge.
|
|
24
|
+
|
|
3
25
|
## 0.2.0
|
|
4
26
|
|
|
5
27
|
- 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,34 @@ 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
|
+
|
|
167
|
+
### Stream cleanup (fixed in 0.3.1)
|
|
168
|
+
|
|
169
|
+
Rejected oversized bodies, refused redirects and aborted reads request stream
|
|
170
|
+
cancellation without waiting for producer cleanup. A stalled or rejected cleanup
|
|
171
|
+
promise cannot hold a concurrency slot or replace the original HTTP error.
|
|
172
|
+
Readers release their locks on success and failure; successful bodies retain their
|
|
173
|
+
original bytes. Cleanup is best-effort: an injected stream producer still owns its
|
|
174
|
+
underlying resources. This does not cancel or undo payment settlement, and does
|
|
175
|
+
not add payment retries.
|
|
176
|
+
|
|
149
177
|
### Commands
|
|
150
178
|
|
|
151
179
|
```sh
|
package/README.zh-CN.md
CHANGED
|
@@ -123,6 +123,27 @@ 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
|
+
|
|
139
|
+
### 数据流清理(0.3.1 修复)
|
|
140
|
+
|
|
141
|
+
拒绝超大请求/响应、拒绝上游重定向或取消读取时,会发起数据流取消,
|
|
142
|
+
但不会等待生产者完成清理。清理卡住或报错不会占住并发名额,也不会覆盖原始错误。
|
|
143
|
+
读取器在成功和失败时均释放锁,正常响应内容保持不变。
|
|
144
|
+
清理属于尽力执行:自定义流生产者仍须管理底层资源。
|
|
145
|
+
此改动不会取消或撤销付款结算,也不增加付款重试。
|
|
146
|
+
|
|
126
147
|
### 检查命令
|
|
127
148
|
|
|
128
149
|
```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/dist/proxy.js
CHANGED
|
@@ -44,7 +44,13 @@ export async function readLimited(stream, limit, signal) {
|
|
|
44
44
|
if (!stream)
|
|
45
45
|
return new Uint8Array();
|
|
46
46
|
const reader = stream.getReader();
|
|
47
|
+
let completed = false;
|
|
48
|
+
let cancelled = false;
|
|
47
49
|
const cancel = () => {
|
|
50
|
+
if (cancelled)
|
|
51
|
+
return;
|
|
52
|
+
cancelled = true;
|
|
53
|
+
// Cleanup belongs to the stream producer and must not block a failure response.
|
|
48
54
|
void reader.cancel().catch(() => { });
|
|
49
55
|
};
|
|
50
56
|
signal?.addEventListener("abort", cancel, { once: true });
|
|
@@ -55,11 +61,12 @@ export async function readLimited(stream, limit, signal) {
|
|
|
55
61
|
signal?.throwIfAborted();
|
|
56
62
|
const { done, value } = await reader.read();
|
|
57
63
|
signal?.throwIfAborted();
|
|
58
|
-
if (done)
|
|
64
|
+
if (done) {
|
|
65
|
+
completed = true;
|
|
59
66
|
break;
|
|
67
|
+
}
|
|
60
68
|
size += value.byteLength;
|
|
61
69
|
if (size > limit) {
|
|
62
|
-
await reader.cancel();
|
|
63
70
|
throw new BodyTooLarge();
|
|
64
71
|
}
|
|
65
72
|
chunks.push(value);
|
|
@@ -67,6 +74,8 @@ export async function readLimited(stream, limit, signal) {
|
|
|
67
74
|
}
|
|
68
75
|
finally {
|
|
69
76
|
signal?.removeEventListener("abort", cancel);
|
|
77
|
+
if (!completed)
|
|
78
|
+
cancel();
|
|
70
79
|
reader.releaseLock();
|
|
71
80
|
}
|
|
72
81
|
const output = new Uint8Array(size);
|
|
@@ -121,7 +130,7 @@ export async function proxy(request, config, fetchUpstream) {
|
|
|
121
130
|
}));
|
|
122
131
|
// No redirect following: an upstream cannot forward the injected credential to another host.
|
|
123
132
|
if (upstream.status >= 300 && upstream.status < 400) {
|
|
124
|
-
|
|
133
|
+
void upstream.body?.cancel().catch(() => { });
|
|
125
134
|
return Response.json({ error: "upstream_redirect_refused" }, { status: 502 });
|
|
126
135
|
}
|
|
127
136
|
const bytes = await readLimited(upstream.body, config.maxBodyBytes, controller.signal);
|
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
|
+
结算超时按结果未知处理,不宣称一定未扣款;测试不涉及真实链上付款。
|
package/docs/week-4.md
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Week 4: non-blocking stream cleanup
|
|
2
|
+
|
|
3
|
+
Continue the Kite x402 Bun/Hono wrapper in the same repository.
|
|
4
|
+
|
|
5
|
+
## Problem
|
|
6
|
+
|
|
7
|
+
Version 0.3.0 awaited stream cancellation when rejecting oversized bodies and
|
|
8
|
+
upstream redirects. An asynchronous producer cleanup that never resolves could
|
|
9
|
+
hold the entire request and concurrency slot indefinitely. A rejecting cleanup
|
|
10
|
+
could also replace the intended error. Already-aborted reads released the reader
|
|
11
|
+
lock but did not cancel the source.
|
|
12
|
+
|
|
13
|
+
## Change and evidence
|
|
14
|
+
|
|
15
|
+
Initiate cancellation without awaiting producer cleanup, handle cleanup rejection,
|
|
16
|
+
cancel unfinished reads once, and always release the reader lock. Successful
|
|
17
|
+
reads keep their exact bytes and do not cancel completed streams.
|
|
18
|
+
|
|
19
|
+
Nine regression tests cover pending and rejecting cancellation for oversized
|
|
20
|
+
requests, oversized responses and redirects; they verify original HTTP errors,
|
|
21
|
+
no settlement or payment receipt, health availability and capacity recovery using
|
|
22
|
+
an unpaid challenge. Additional cases cover already-aborted reads, abort during a
|
|
23
|
+
pending read, and successful multi-chunk reads at the exact size limit.
|
|
24
|
+
|
|
25
|
+
Against the previous source, seven of these nine tests fail. With the fix all nine
|
|
26
|
+
pass. Test payment verification is simulated; no real on-chain payment is claimed.
|
|
27
|
+
The fix is included in version 0.3.1; registry publication is verified separately.
|
|
28
|
+
|
|
29
|
+
Cancellation is best-effort, not proof the producer released external resources.
|
|
30
|
+
An injected stream must manage its own resources. This change neither aborts an
|
|
31
|
+
in-flight settlement nor retries payment or undoes an upstream action.
|
|
32
|
+
|
|
33
|
+
## 可提交说明
|
|
34
|
+
|
|
35
|
+
第四周修复数据流清理阻塞请求的问题:超大请求/响应和上游重定向被拒绝时,
|
|
36
|
+
发起取消但不等待生产者清理,防止清理挂起占住并发名额;清理异常不再覆盖原始错误。
|
|
37
|
+
补齐已取消请求的流清理,确保读取器释放锁。新增 9 项回归测试,覆盖挂起/失败清理、
|
|
38
|
+
原始错误保留、不结算、不返回付款收据、健康检查、并发恢复以及正常响应字节完整性。
|