repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/devdocs/src/adapters/network.ts
Rawtype ProviderCode =
| "busy"
| "network"
| "timeout"
| "aborted"
| "redirect"
| "limit"
| "invalid"
| "auth"
| "rate-limit"
| "unavailable"
| "version";
export class ProviderError extends Error {
readonly code: ProviderCode;
readonly retryAfterMs: number | null;
constructor(code: ProviderCode, retryAfterMs: number | null = null) {
super(`documentation provider: ${code}`);
this.name = "ProviderError";
this.code = code;
this.retryAfterMs = retryAfterMs;
}
}
export function httpError(response: Response): ProviderError {
const retry = response.headers.get("retry-after");
const ms =
retry === null
? null
: /^\d+(?:\.\d+)?$/.test(retry)
? Number(retry) * 1000
: Date.parse(retry) - Date.now();
const delay = ms !== null && Number.isFinite(ms) ? Math.max(0, ms) : null;
return new ProviderError(
response.status === 401 || response.status === 403
? "auth"
: response.status === 429
? "rate-limit"
: "unavailable",
delay,
);
}
export type NetworkOptions = {
fetch?: typeof fetch;
timeoutMs?: number;
};
type Result = { text: string; validator: string | null; unchanged: boolean };
type NetworkRequest = {
signal?: AbortSignal | undefined;
maxBytes: number;
validator?: string | null | undefined;
apiKey?: string | undefined;
};
export function parseJson(text: string, secret?: string): unknown {
try {
return JSON.parse(text, (_key, value: unknown) =>
typeof value === "string" && secret
? value.split(secret).join("[redacted]")
: value,
);
} catch {
throw new ProviderError("invalid");
}
}
export function record(value: unknown): Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value)
? (value as Record<string, unknown>)
: {};
}
export function string(value: unknown): string {
return typeof value === "string" ? value : "";
}
// Only these fixed public service origins are contacted, never provider-supplied URLs.
export function createNetwork(
origin:
| "https://devdocs.io"
| "https://documents.devdocs.io"
| "https://context7.com",
options: NetworkOptions = {},
) {
let retryAt = 0;
return async (input: string, request: NetworkRequest): Promise<Result> => {
if (retryAt > Date.now())
throw new ProviderError("rate-limit", retryAt - Date.now());
const controller = new AbortController();
let timedOut = false;
const abort = () => controller.abort();
request.signal?.addEventListener("abort", abort, { once: true });
if (request.signal?.aborted) controller.abort();
const timeout = Math.max(1, Math.min(options.timeoutMs ?? 10000, 30000));
let timer: ReturnType<typeof setTimeout> | undefined;
let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
const aborted = new Promise<never>((_, reject) => {
const fail = () =>
reject(new ProviderError(timedOut ? "timeout" : "aborted"));
controller.signal.addEventListener("abort", fail, { once: true });
if (controller.signal.aborted) fail();
timer = setTimeout(() => {
timedOut = true;
controller.abort();
}, timeout);
});
const secret = request.apiKey;
const scrub = (value: string) => {
if (!secret) return value;
for (const form of [
secret,
encodeURIComponent(secret),
JSON.stringify(secret).slice(1, -1),
])
value = value.split(form).join("[redacted]");
return value;
};
const work = async (): Promise<Result> => {
let url = new URL(input);
const headers = new Headers({
Accept: "application/json, text/html;q=0.9",
});
if (secret) headers.set("Authorization", `Bearer ${secret}`);
if (request.validator) {
const v = record(parseJson(request.validator));
if (typeof v["etag"] === "string")
headers.set("If-None-Match", v["etag"]);
if (typeof v["modified"] === "string")
headers.set("If-Modified-Since", v["modified"]);
}
for (let redirects = 0; redirects <= 3; redirects++) {
if (url.origin !== origin || url.username || url.password)
throw new ProviderError("redirect");
controller.signal.throwIfAborted();
const response = await (options.fetch ?? globalThis.fetch)(url.href, {
headers,
signal: controller.signal,
redirect: "manual",
});
if (controller.signal.aborted) {
void response.body?.cancel().catch(() => {});
controller.signal.throwIfAborted();
}
if ([301, 302, 303, 307, 308].includes(response.status)) {
void response.body?.cancel().catch(() => {});
const location = response.headers.get("location");
if (!location || redirects === 3) throw new ProviderError("redirect");
url = new URL(location, url);
continue;
}
if (response.status === 304) {
void response.body?.cancel().catch(() => {});
if (!request.validator) throw new ProviderError("invalid");
return { text: "", validator: request.validator, unchanged: true };
}
if (response.status !== 200) {
void response.body?.cancel().catch(() => {});
const error = httpError(response);
if (error.retryAfterMs !== null)
retryAt = Date.now() + error.retryAfterMs;
throw error;
}
if (Number(response.headers.get("content-length")) > request.maxBytes) {
void response.body?.cancel().catch(() => {});
throw new ProviderError("limit");
}
const chunks: Uint8Array[] = [];
let bytes = 0;
reader = response.body?.getReader();
if (reader)
for (;;) {
const next = await reader.read();
if (next.done) break;
bytes += next.value.byteLength;
if (bytes > request.maxBytes) throw new ProviderError("limit");
chunks.push(next.value);
}
const etag = response.headers.get("etag");
const modified = response.headers.get("last-modified");
return {
text: scrub(Buffer.concat(chunks).toString("utf8")),
validator:
etag || modified ? scrub(JSON.stringify({ etag, modified })) : null,
unchanged: false,
};
}
throw new ProviderError("redirect");
};
try {
return await Promise.race([aborted, work()]);
} catch (error) {
if (error instanceof ProviderError) throw error;
throw new ProviderError(
controller.signal.aborted
? timedOut
? "timeout"
: "aborted"
: "network",
);
} finally {
clearTimeout(timer);
request.signal?.removeEventListener("abort", abort);
controller.abort();
void reader?.cancel().catch(() => {});
}
};
}