http.ts

mcp-server/src/lib/http.ts

1. import { assertLiveRequestsAllowed, type PlinthConfig } from "./config.js";
2. import { PlinthApiError, RateLimitError } from "./errors.js";
3. import {
4. assertReadMethod,
5. assertSafeParams,
6. assertUrlIsRead,
7. RESERVED_PARAM_KEYS,
8. type ReadMethod,
9. } from "./guard.js";
10. import { RATE_LIMIT_RETRY_MS, sleep, type RateLimiter } from "./rateLimit.js";
12. /** Ambient context for a Plinth request: env-derived config + optional limiter. */
13. export interface PlinthRequestContext {
14. config: PlinthConfig;
15. limiter?: RateLimiter;
16. }
18. /** Query params (excluding `method` and `api_key`, which are added here). */
19. export type PlinthParams = Record<string, string | number | undefined>;
21. /**
22. * Build the request URL for a read method. Pure and side-effect free, so it is
23. * safe to unit test without touching the network. `api_key` is appended by
24. * plinthRequest().
25. *
26. * Failsafe: server-controlled params (`method`, `api_key`) are skipped in the
27. * caller loop and `method` is set LAST, so no caller-supplied param can
28. * overwrite the dispatched method, even through the free-form passthrough tools.
29. */
30. export function buildUrl(baseUrl: string, method: ReadMethod, params: PlinthParams): URL {
31. assertReadMethod(method);
32. const url = new URL(baseUrl);
33. for (const [key, value] of Object.entries(params)) {
34. if (RESERVED_PARAM_KEYS.has(key.trim().toLowerCase())) continue;
35. if (value !== undefined && value !== "") {
36. url.searchParams.set(key, String(value));
37. }
38. }
39. // Set last so the dispatched method can never be shadowed by a caller param.
40. url.searchParams.set("method", method);
41. return url;
42. }
44. /**
45. * Detect the API's documented error shapes. Success bodies never carry these
46. * keys, so a hit means the call failed even though HTTP status was 200.
47. *
48. * Note: a failed lookup can come back under `error` or as `notice: "No match"`;
49. * on orders.splitShipments "No match" means "not a multi-address order" rather
50. * than a hard failure. Callers disambiguate via PlinthApiError.raw.
51. */
52. export function detectApiError(body: unknown): PlinthApiError | undefined {
53. if (body && typeof body === "object") {
54. const rec = body as Record<string, unknown>;
55. const message =
56. (typeof rec.error === "string" && rec.error) ||
57. (typeof rec.notice === "string" && rec.notice) ||
58. undefined;
59. if (message) {
60. if (/too many requests/i.test(message)) return new RateLimitError(body);
61. return new PlinthApiError(message, body);
62. }
63. }
64. return undefined;
65. }
67. /**
68. * Execute a single read request against the Plinth API.
69. *
70. * Runtime-agnostic: uses only `fetch` and `URL`, both native to the Cloudflare
71. * Workers isolate and to Node 18+. Config is injected (no globals) so the same
72. * function runs unchanged on either runtime.
73. *
74. * Gated: assertLiveRequestsAllowed() throws unless the operator has explicitly
75. * opted in (PLINTH_ALLOW_LIVE_REQUESTS=true and an API key).
76. *
77. * Rate limiting: when a limiter is supplied on the context, every attempt first
78. * awaits limiter.acquire(), which delays until a slot is free so the 10/10s cap
79. * is never exceeded (see lib/rateLimit.ts). As a backstop, a RateLimitError
80. * that still slips through triggers one retry after a full window.
81. */
82. export async function plinthRequest(
83. ctx: PlinthRequestContext,
84. method: ReadMethod,
85. params: PlinthParams = {},
86. ): Promise<unknown> {
87. const { config, limiter } = ctx;
88. assertLiveRequestsAllowed(config);
89. // Failsafe layers 1 & 2: method must be on the read allowlist, and no
90. // caller param may carry a reserved key or signal write intent.
91. assertReadMethod(method);
92. assertSafeParams(params);
94. const url = buildUrl(config.baseUrl, method, params);
95. url.searchParams.set("api_key", config.apiKey as string);
97. // Failsafe layer 4: final check that the wire URL is a read before any I/O.
98. assertUrlIsRead(url);
100. const MAX_ATTEMPTS = 2;
101. for (let attempt = 1; ; attempt++) {
102. // Respect the 10/10s cap: the limiter delays until a slot is free.
103. if (limiter) await limiter.acquire();
105. const res = await fetch(url, { method: "GET" });
106. const body: unknown = await res.json();
108. const apiError = detectApiError(body);
109. if (!apiError) return body;
111. // Backstop: a rate-limit error slipped through; wait a window, retry once.
112. if (apiError instanceof RateLimitError && attempt < MAX_ATTEMPTS) {
113. await sleep(RATE_LIMIT_RETRY_MS);
114. continue;
115. }
116. throw apiError;
117. }
118. }