@akilin/api-kit 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +288 -2
- package/dist/api-error.d.ts +100 -0
- package/dist/api-error.js +30 -0
- package/dist/body.d.ts +2 -0
- package/dist/body.js +20 -0
- package/dist/create-api.d.ts +65 -0
- package/dist/create-api.js +48 -0
- package/dist/deadline.d.ts +16 -0
- package/dist/deadline.js +56 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +2 -0
- package/dist/paged-data.d.ts +4 -0
- package/dist/paged-data.js +1 -0
- package/dist/query.d.ts +5 -0
- package/dist/query.js +22 -0
- package/dist/request.d.ts +80 -0
- package/dist/request.js +179 -0
- package/dist/response.d.ts +17 -0
- package/dist/response.js +79 -0
- package/dist/send.d.ts +50 -0
- package/dist/send.js +68 -0
- package/dist/telemetry.d.ts +15 -0
- package/dist/telemetry.js +67 -0
- package/dist/url.d.ts +10 -0
- package/dist/url.js +39 -0
- package/package.json +41 -4
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { send } from './send.js';
|
|
2
|
+
import { isAbsoluteUrl, joinUrl, originOf } from './url.js';
|
|
3
|
+
const defaultTelemetryUrl = '/api/client-logs';
|
|
4
|
+
// For the snippet and the URL. Characters, not bytes: text that JSON escapes heavily (a binary body read as text) can
|
|
5
|
+
// still take a trace past the server's ~16 KB cap, and that trace fails like any other.
|
|
6
|
+
const maxTextLength = 2000;
|
|
7
|
+
// Capped per client: during an outage (a proxy answering every call with a 502 page) each failed call would otherwise
|
|
8
|
+
// add a telemetry request, most likely failing too. Fixed, not an option.
|
|
9
|
+
const maxTracesPerWindow = 10;
|
|
10
|
+
const traceWindowMs = 60_000;
|
|
11
|
+
export function createReporter(config, options = {}) {
|
|
12
|
+
const url = telemetryUrl(config.baseUrl, options.url ?? defaultTelemetryUrl);
|
|
13
|
+
const sentAt = [];
|
|
14
|
+
const takeSlot = () => {
|
|
15
|
+
const now = Date.now();
|
|
16
|
+
while (sentAt.length > 0 && sentAt[0] <= now - traceWindowMs)
|
|
17
|
+
sentAt.shift();
|
|
18
|
+
if (sentAt.length >= maxTracesPerWindow)
|
|
19
|
+
return false;
|
|
20
|
+
sentAt.push(now);
|
|
21
|
+
return true;
|
|
22
|
+
};
|
|
23
|
+
return (request, error, durationMs) => {
|
|
24
|
+
if (!takeSlot())
|
|
25
|
+
return;
|
|
26
|
+
let body;
|
|
27
|
+
try {
|
|
28
|
+
const trace = {
|
|
29
|
+
kind: error.kind,
|
|
30
|
+
method: request.method,
|
|
31
|
+
url: truncate(withoutQuery(joinUrl(config.baseUrl, request.url))),
|
|
32
|
+
status: error.status,
|
|
33
|
+
traceId: error.traceId,
|
|
34
|
+
responseBodySnippet: truncate(error.responseText),
|
|
35
|
+
durationMs,
|
|
36
|
+
timestamp: new Date().toISOString(),
|
|
37
|
+
context: options.context?.(),
|
|
38
|
+
};
|
|
39
|
+
// Inside the try, so a `context()` result with a BigInt or a cycle drops the trace like a throwing `context()`:
|
|
40
|
+
// telemetry never breaks the app.
|
|
41
|
+
body = JSON.stringify(trace);
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
// Straight to `send`, never through an `ApiRequest`: a failing telemetry request runs no handler or policy and is
|
|
47
|
+
// never reported itself (no loop). `send` resolves with the failure rather than rejecting, so it is simply
|
|
48
|
+
// dropped. The client's config is kept, so its `headers`, `credentials` and `fetch` apply to traces too (auth for
|
|
49
|
+
// the endpoint), the headers only on the origin of `baseUrl` like any request's; `unprefixed`, as the url already
|
|
50
|
+
// has its prefix. `keepalive`, so a full-page navigation in `onUnexpected` or `onUnauthorized`, right after this,
|
|
51
|
+
// doesn't cancel the trace (a trace stays well under keepalive's 64 KB).
|
|
52
|
+
void send(config, { method: 'POST', url, body, keepalive: true, unprefixed: true });
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
function withoutQuery(url) {
|
|
56
|
+
const end = url.search(/[?#]/);
|
|
57
|
+
return end < 0 ? url : url.slice(0, end);
|
|
58
|
+
}
|
|
59
|
+
// The `replace` drops the first half of a surrogate pair the cut split.
|
|
60
|
+
function truncate(text) {
|
|
61
|
+
return text.length <= maxTextLength ? text : text.slice(0, maxTextLength).replace(/[\ud800-\udbff]$/, '');
|
|
62
|
+
}
|
|
63
|
+
// Only the origin of `baseUrl` is prefixed, not its path, so the default `/api/client-logs` reaches the API's server
|
|
64
|
+
// even when the API is on another origin than the app.
|
|
65
|
+
function telemetryUrl(baseUrl, url) {
|
|
66
|
+
return isAbsoluteUrl(url) ? url : joinUrl(originOf(baseUrl), url);
|
|
67
|
+
}
|
package/dist/url.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export declare function isAbsoluteUrl(url: string): boolean;
|
|
2
|
+
export declare function originOf(url: string): string;
|
|
3
|
+
/**
|
|
4
|
+
* Whether `url` is fetched from the same origin as `baseUrl`: both relative to the page (a path, `?…`, `#…`), or both
|
|
5
|
+
* absolute with the same scheme and authority as written (case-insensitive; `https://host` and `https://host:443`, or
|
|
6
|
+
* `//host` and `https://host`, differ). Anything else, a url fetch would read another way than it reads here included,
|
|
7
|
+
* is another origin.
|
|
8
|
+
*/
|
|
9
|
+
export declare function isSameOrigin(baseUrl: string, url: string): boolean;
|
|
10
|
+
export declare function joinUrl(baseUrl: string, url: string): string;
|
package/dist/url.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// Parsed by hand: `URL` is outside the platform subset (platform.d.ts).
|
|
2
|
+
// Absolute is only `scheme://` or `//`. Any other `name:` start is a path (`items:batchGet`, `v1:search`), as relative
|
|
3
|
+
// paths are in practice.
|
|
4
|
+
const absolute = /^([a-z][a-z\d+.-]*:)?\/\//i;
|
|
5
|
+
export function isAbsoluteUrl(url) {
|
|
6
|
+
return absolute.test(url);
|
|
7
|
+
}
|
|
8
|
+
export function originOf(url) {
|
|
9
|
+
return /^([a-z][a-z\d+.-]*:)?\/\/[^/?#]*/i.exec(url)?.[0] ?? '';
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Whether `url` is fetched from the same origin as `baseUrl`: both relative to the page (a path, `?…`, `#…`), or both
|
|
13
|
+
* absolute with the same scheme and authority as written (case-insensitive; `https://host` and `https://host:443`, or
|
|
14
|
+
* `//host` and `https://host`, differ). Anything else, a url fetch would read another way than it reads here included,
|
|
15
|
+
* is another origin.
|
|
16
|
+
*/
|
|
17
|
+
export function isSameOrigin(baseUrl, url) {
|
|
18
|
+
const base = originKey(baseUrl);
|
|
19
|
+
return base !== undefined && base === originKey(url);
|
|
20
|
+
}
|
|
21
|
+
// `''` for a url relative to the page, `undefined` for one whose origin can't be told (a scheme without `//`, which
|
|
22
|
+
// fetch may read as a host: `https:evil.com`). First the WHATWG URL parser's own clean-up: it drops leading and
|
|
23
|
+
// trailing C0 controls and spaces, and every tab or newline, so `/\t/evil.com` is `//evil.com`. A `\` counts as a `/`
|
|
24
|
+
// before the host (`/\evil.com` is `//evil.com` in a browser) and stays in the authority after it, so
|
|
25
|
+
// `https://api.example.com\@evil.com` matches no base.
|
|
26
|
+
function originKey(url) {
|
|
27
|
+
const cleaned = url.replace(/^[\u0000- ]+|[\u0000- ]+$/g, '').replace(/[\t\n\r]/g, '').toLowerCase();
|
|
28
|
+
const withAuthority = /^([a-z][a-z\d+.-]*:)?[/\\]{2}[^/?#]*/.exec(cleaned);
|
|
29
|
+
if (withAuthority)
|
|
30
|
+
return withAuthority[0];
|
|
31
|
+
return /^[a-z][a-z\d+.-]*:/.test(cleaned) ? undefined : '';
|
|
32
|
+
}
|
|
33
|
+
export function joinUrl(baseUrl, url) {
|
|
34
|
+
if (baseUrl === '' || isAbsoluteUrl(url))
|
|
35
|
+
return url;
|
|
36
|
+
if (url === '' || url.startsWith('?') || url.startsWith('#'))
|
|
37
|
+
return baseUrl + url;
|
|
38
|
+
return `${baseUrl.replace(/\/+$/, '')}/${url.replace(/^\//, '')}`;
|
|
39
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@akilin/api-kit",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Library-agnostic TypeScript API client for akilin.ApiKit (RFC 9457 Problem Details) APIs. Personal project — not intended for use by others; no support or stability guarantees.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "akilin",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/akilin/api-kit.git",
|
|
10
|
+
"directory": "src/ts/api-kit"
|
|
11
|
+
},
|
|
12
|
+
"keywords": [
|
|
13
|
+
"api-client",
|
|
14
|
+
"fetch",
|
|
15
|
+
"problem-details",
|
|
16
|
+
"rfc9457",
|
|
17
|
+
"react-native"
|
|
18
|
+
],
|
|
19
|
+
"type": "module",
|
|
20
|
+
"sideEffects": false,
|
|
21
|
+
"exports": {
|
|
22
|
+
".": {
|
|
23
|
+
"types": "./dist/index.d.ts",
|
|
24
|
+
"default": "./dist/index.js"
|
|
25
|
+
},
|
|
26
|
+
"./package.json": "./package.json"
|
|
27
|
+
},
|
|
28
|
+
"main": "./dist/index.js",
|
|
29
|
+
"types": "./dist/index.d.ts",
|
|
30
|
+
"files": [
|
|
31
|
+
"dist"
|
|
32
|
+
],
|
|
33
|
+
"publishConfig": {
|
|
34
|
+
"access": "public"
|
|
35
|
+
},
|
|
36
|
+
"scripts": {
|
|
37
|
+
"build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
|
|
38
|
+
"prepack": "npm run build"
|
|
39
|
+
},
|
|
40
|
+
"devDependencies": {
|
|
41
|
+
"typescript": "^7.0.2"
|
|
42
|
+
}
|
|
43
|
+
}
|