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 CHANGED
@@ -10,3 +10,4 @@ PORT=8080
10
10
  # UPSTREAM_TIMEOUT_MS=10000
11
11
  # MAX_BODY_BYTES=1048576
12
12
  # MAX_CONCURRENT_REQUESTS=64
13
+ # FACILITATOR_TIMEOUT_MS=90000
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 have their own 90-second timeout;
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({ url: config.facilitatorUrl });
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
@@ -12,5 +12,6 @@ export interface Config {
12
12
  timeoutMs: number;
13
13
  maxBodyBytes: number;
14
14
  maxConcurrentRequests?: number;
15
+ facilitatorTimeoutMs?: number;
15
16
  }
16
17
  export declare function loadConfig(env?: Record<string, string | undefined>): Config;
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
- await upstream.body?.cancel();
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
+ 原始错误保留、不结算、不返回付款收据、健康检查、并发恢复以及正常响应字节完整性。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kite-x402-hono",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Bun and Hono reverse proxy for x402 payments on Kite",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",