@tansy/request-logs 0.0.0-stage → 0.1.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/CHANGELOG.md ADDED
@@ -0,0 +1,9 @@
1
+ # Changelog
2
+
3
+ What changed in each release of `@tansy/request-logs`. Releases up to 0.1.0 went out with every other package
4
+ on one version and are described in [tansy's changelog](../../CHANGELOG.md).
5
+
6
+ ## 0.1.1 — 2026-11-22
7
+
8
+ No changes of its own. Released beside `tansy` 0.1.1, from which every package moves on its own
9
+ version, and it now requires it: the `tansy` peer range is ^0.1.1.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mohamed Salah
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ <!-- Generated by scripts/package-metadata.mjs. Change that script, not this file. -->
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # @tansy/request-logs
4
+
5
+ A log of every API request for tansy: kept in the database and shown on the dashboard, sent to S3 or any storage, an HTTP log drain, or the console, or all of them.
6
+
7
+ ```bash
8
+ npm install @tansy/request-logs
9
+ ```
10
+
11
+ Add it to `tansy.config.ts`. See [the request-logs plugin documentation](https://github.com/mhmdsalahsebai/tansy/blob/main/docs/plugins/request-logs.md) for what it adds and the options it takes.
12
+
13
+ A first-party plugin for [tansy](https://github.com/mhmdsalahsebai/tansy), a self-hosted, runtime-schema CMS for Next.js. MIT licensed.
package/admin.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ declare const _default: import("tansy/admin").AdminPluginParts;
2
+ export default _default;
package/admin.js ADDED
@@ -0,0 +1,17 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { adminPath, defineAdminPlugin, PageHeader, TabLinks } from "tansy/admin";
3
+ import { getT } from "tansy/server";
4
+ import { RequestLogView } from "./view";
5
+ async function RequestLogs({ user }) {
6
+ const { t } = await getT(user.id);
7
+ const word = (key) => t(`ext.request-logs.${key}`);
8
+ const canSet = user.permissions.includes("setting:update");
9
+ return (_jsxs("div", { className: "cms-gutter", children: [_jsx(PageHeader, { title: word("pages.request-logs"), description: word("description") }), canSet && (_jsx(TabLinks, { label: word("pages.request-logs"), links: [
10
+ { href: adminPath("/ext/request-logs"), label: word("tabs.logs"), active: true },
11
+ { href: adminPath("/extensions/request-logs/settings"), label: word("tabs.settings") },
12
+ ] })), _jsx(RequestLogView, {})] }));
13
+ }
14
+ export default defineAdminPlugin({
15
+ pages: [{ path: "request-logs", title: "Request logs", permission: "ext.request-logs:read", component: RequestLogs }],
16
+ section: { title: "Request logs", icon: "logs", items: [{ page: "request-logs" }, { settings: true }] },
17
+ });
@@ -0,0 +1,48 @@
1
+ import type { StorageAdapter } from "tansy/storage";
2
+ import type { RequestLogEntry } from "./logic";
3
+ /**
4
+ * Somewhere outside the database that request logs are sent, as they are written. Anything
5
+ * with a name and a `write` works: a log service's API, a queue, a file. `write` gets a few
6
+ * seconds' worth of entries at a time. Throwing means "try again later": the entries are
7
+ * kept for the next write, up to a limit.
8
+ */
9
+ export interface RequestLogDestination {
10
+ /** Lowercase letters, digits and hyphens. Unique among the plugin's destinations. */
11
+ name: string;
12
+ /** Shown on the dashboard, such as "S3 (logs-bucket)". */
13
+ label: string;
14
+ write(entries: RequestLogEntry[]): Promise<void>;
15
+ }
16
+ export declare function checkedDestinations(destinations: RequestLogDestination[]): RequestLogDestination[];
17
+ /** One JSON object a line, the format log tools read. */
18
+ export declare const jsonLines: (entries: RequestLogEntry[]) => string;
19
+ /** Where a file of entries goes: `<prefix>/2026/11/16/12-30-05.123Z-<random>.jsonl`, so a day's files list together and sort by time. */
20
+ export declare function fileKey(prefix: string, at: string, random: string): string;
21
+ /**
22
+ * Files of JSON lines in any storage the CMS supports: `s3Storage(...)` from tansy/storage
23
+ * for S3, R2, B2, MinIO and the rest, or a storage plugin's adapter. One file a write.
24
+ */
25
+ export declare function storageDestination(adapter: StorageAdapter, options?: {
26
+ prefix?: string;
27
+ name?: string;
28
+ label?: string;
29
+ }): RequestLogDestination;
30
+ export interface HttpDestinationOptions {
31
+ /** Where entries are POSTed, such as a log service's ingest URL. Must be https, except on localhost. */
32
+ url: string;
33
+ /** Such as an Authorization header with the service's token. Read it from an environment variable. */
34
+ headers?: Record<string, string>;
35
+ /** "ndjson", one entry a line, or "json", an array. "ndjson" when left out. */
36
+ format?: "ndjson" | "json";
37
+ name?: string;
38
+ label?: string;
39
+ /** Milliseconds. 10 seconds when left out. */
40
+ timeoutMs?: number;
41
+ }
42
+ /** POSTs entries to a log service, such as Axiom, Better Stack, Datadog, Grafana Loki through a gateway, or your own endpoint. */
43
+ export declare function httpDestination(options: HttpDestinationOptions): RequestLogDestination;
44
+ /** One JSON line an entry on standard output, for a host that collects it, such as Vercel, Fly, Docker or Kubernetes. */
45
+ export declare function consoleDestination(options?: {
46
+ name?: string;
47
+ label?: string;
48
+ }): RequestLogDestination;
@@ -0,0 +1,78 @@
1
+ const NAME = /^[a-z][a-z0-9-]{0,30}$/;
2
+ export function checkedDestinations(destinations) {
3
+ const seen = new Set();
4
+ for (const destination of destinations) {
5
+ if (!NAME.test(destination.name))
6
+ throw new Error(`Request logs: "${destination.name}" isn't a destination name. Use lowercase letters, digits and hyphens.`);
7
+ if (seen.has(destination.name))
8
+ throw new Error(`Request logs: the destination "${destination.name}" is listed twice.`);
9
+ if (typeof destination.write !== "function")
10
+ throw new Error(`Request logs: the destination "${destination.name}" has no write().`);
11
+ seen.add(destination.name);
12
+ }
13
+ return destinations;
14
+ }
15
+ /** One JSON object a line, the format log tools read. */
16
+ export const jsonLines = (entries) => `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
17
+ /** Where a file of entries goes: `<prefix>/2026/11/16/12-30-05.123Z-<random>.jsonl`, so a day's files list together and sort by time. */
18
+ export function fileKey(prefix, at, random) {
19
+ const [date, time] = at.split("T");
20
+ const folder = [prefix.replace(/^\/+|\/+$/g, ""), ...date.split("-")].filter(Boolean).join("/");
21
+ return `${folder}/${time.replace(/:/g, "-")}-${random}.jsonl`;
22
+ }
23
+ /**
24
+ * Files of JSON lines in any storage the CMS supports: `s3Storage(...)` from tansy/storage
25
+ * for S3, R2, B2, MinIO and the rest, or a storage plugin's adapter. One file a write.
26
+ */
27
+ export function storageDestination(adapter, options = {}) {
28
+ const prefix = options.prefix ?? "request-logs";
29
+ return {
30
+ name: options.name ?? "storage",
31
+ label: options.label ?? `Storage (${adapter.name})`,
32
+ async write(entries) {
33
+ if (!entries.length)
34
+ return;
35
+ adapter.assertUsable?.();
36
+ const bytes = new TextEncoder().encode(jsonLines(entries));
37
+ const key = fileKey(prefix, entries[0].at, crypto.randomUUID().slice(0, 8));
38
+ const body = new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } });
39
+ await adapter.put(key, body, { size: bytes.byteLength, contentType: "application/x-ndjson" });
40
+ },
41
+ };
42
+ }
43
+ /** POSTs entries to a log service, such as Axiom, Better Stack, Datadog, Grafana Loki through a gateway, or your own endpoint. */
44
+ export function httpDestination(options) {
45
+ const url = new URL(options.url);
46
+ const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
47
+ if (url.protocol !== "https:" && !(local && url.protocol === "http:"))
48
+ throw new Error("Request logs: an HTTP destination's url must use https.");
49
+ const format = options.format ?? "ndjson";
50
+ return {
51
+ name: options.name ?? "http",
52
+ label: options.label ?? url.host,
53
+ async write(entries) {
54
+ if (!entries.length)
55
+ return;
56
+ const response = await fetch(url, {
57
+ method: "POST",
58
+ headers: { "content-type": format === "json" ? "application/json" : "application/x-ndjson", ...options.headers },
59
+ body: format === "json" ? JSON.stringify(entries) : jsonLines(entries),
60
+ signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
61
+ redirect: "error",
62
+ });
63
+ if (!response.ok)
64
+ throw new Error(`${url.host} answered ${response.status}.`);
65
+ },
66
+ };
67
+ }
68
+ /** One JSON line an entry on standard output, for a host that collects it, such as Vercel, Fly, Docker or Kubernetes. */
69
+ export function consoleDestination(options = {}) {
70
+ return {
71
+ name: options.name ?? "console",
72
+ label: options.label ?? "Server output",
73
+ async write(entries) {
74
+ for (const entry of entries)
75
+ console.log(JSON.stringify({ type: "request", ...entry }));
76
+ },
77
+ };
78
+ }
package/index.d.ts ADDED
@@ -0,0 +1,23 @@
1
+ import { type RequestLogDestination } from "./destinations";
2
+ import { type Which } from "./logic";
3
+ export { consoleDestination, httpDestination, jsonLines, storageDestination, type HttpDestinationOptions, type RequestLogDestination } from "./destinations";
4
+ export type { RequestLogEntry } from "./logic";
5
+ export interface RequestLogsOptions {
6
+ /**
7
+ * Places outside the database that entries are also sent to: `storageDestination(s3Storage(...))`
8
+ * for S3 and other storage, `httpDestination({ url })` for a log service, `consoleDestination()`
9
+ * for the server's output, or any object with a name and `write`.
10
+ */
11
+ destinations?: RequestLogDestination[];
12
+ /** Whether entries are kept in the database until changed in the settings. On when left out. */
13
+ database?: boolean;
14
+ /** Which requests are logged until changed in the settings. "all" when left out. */
15
+ which?: Which;
16
+ /** How many days entries stay in the database until changed in the settings. 7 when left out. */
17
+ retentionDays?: number;
18
+ }
19
+ /**
20
+ * A log of every API request, kept in the database and shown on the dashboard, sent to S3
21
+ * or any storage, a log service, or the server's output, or all of them. See docs/plugins/request-logs.md.
22
+ */
23
+ export declare function requestLogs(options?: RequestLogsOptions): import("tansy/plugin").CmsPlugin;
package/index.js ADDED
@@ -0,0 +1,173 @@
1
+ import { z } from "zod";
2
+ import { apiPath, definePlugin, defineRoute } from "tansy/plugin";
3
+ import { checkedDestinations } from "./destinations";
4
+ import { messages } from "./messages";
5
+ import { BATCH_PREFIX, batchKey, cutoffKey, findEntries, kept, skipList, toBatches, WHICH } from "./logic";
6
+ export { consoleDestination, httpDestination, jsonLines, storageDestination } from "./destinations";
7
+ const NAME = "request-logs";
8
+ const PERMISSION = "ext.request-logs:read";
9
+ const FLUSH_MS = 2000;
10
+ /** Entries waiting in memory, and per destination for a retry. Past it, new ones are dropped and counted. */
11
+ const MAX_WAITING = 5000;
12
+ const SETTINGS_TTL_MS = 30_000;
13
+ const DEFAULT_SKIP = "/api/realtime";
14
+ const optionsSchema = z.strictObject({
15
+ destinations: z.array(z.object({ name: z.string(), label: z.string(), write: z.custom((write) => typeof write === "function") }).loose()),
16
+ database: z.boolean(),
17
+ which: z.enum(WHICH),
18
+ retentionDays: z.number().int().min(1).max(365),
19
+ });
20
+ /**
21
+ * A log of every API request, kept in the database and shown on the dashboard, sent to S3
22
+ * or any storage, a log service, or the server's output, or all of them. See docs/plugins/request-logs.md.
23
+ */
24
+ export function requestLogs(options = {}) {
25
+ const value = optionsSchema.parse({ destinations: [], database: true, which: "all", retentionDays: 7, ...Object.fromEntries(Object.entries(options).filter(([, option]) => option !== undefined)) });
26
+ const destinations = checkedDestinations(options.destinations ?? []);
27
+ const state = (globalThis.cmsRequestLogs ??= { waiting: [], retry: new Map(), dropped: 0, timer: null, flushing: null, settings: null });
28
+ const own = apiPath(`/ext/${NAME}`);
29
+ const fields = [
30
+ { name: "enabled", type: "boolean", default: true, label: "Log API requests", description: "When off, nothing new is logged anywhere." },
31
+ { name: "which", type: "select", default: value.which, label: "Which requests", description: "Reads that worked are most of them, and the least useful.", options: [{ value: "all", label: "All of them" }, { value: "writes", label: "Changes and errors" }, { value: "errors", label: "Errors only" }] },
32
+ { name: "database", type: "boolean", default: value.database, label: "Keep them in the database", description: "Shown on this page. Turn it off to send them only to the places below." },
33
+ ...(destinations.length ? [{ name: "destinations", type: "boolean", default: true, label: "Also send them outside", description: `To ${destinations.map((destination) => destination.label).join(", ")}.` }] : []),
34
+ { name: "storeIp", type: "boolean", default: true, label: "Keep IP addresses", description: "Off leaves them out, for privacy." },
35
+ { name: "storeUserAgent", type: "boolean", default: true, label: "Keep browsers", description: "The user agent each request sent. Off leaves it out." },
36
+ { name: "skip", type: "text", default: DEFAULT_SKIP, multiline: true, maxLength: 2000, label: "Addresses not to log", description: "One per line, such as /api/realtime. Each covers everything under it." },
37
+ { name: "retentionDays", type: "number", default: value.retentionDays, min: 1, max: 365, integer: true, label: "Keep entries here for (days)", description: "Older entries are deleted each night." },
38
+ ];
39
+ async function settingsOf(context, { fresh = false } = {}) {
40
+ if (!fresh && state.settings && Date.now() - state.settings.at < SETTINGS_TTL_MS)
41
+ return state.settings.value;
42
+ const saved = await context.settings.get();
43
+ const settings = {
44
+ enabled: saved.enabled !== false,
45
+ which: WHICH.includes(saved.which) ? saved.which : value.which,
46
+ database: saved.database === undefined ? value.database : saved.database === true,
47
+ destinations: destinations.length > 0 && saved.destinations !== false,
48
+ storeIp: saved.storeIp !== false,
49
+ // Before this had its own switch, "Keep IP addresses" covered browsers too, so a site that turned that off keeps neither.
50
+ storeUserAgent: saved.storeUserAgent === undefined ? saved.storeIp !== false : saved.storeUserAgent !== false,
51
+ skip: skipList(saved.skip ?? DEFAULT_SKIP),
52
+ retentionDays: Math.min(365, Math.max(1, Number(saved.retentionDays) || value.retentionDays)),
53
+ };
54
+ state.settings = { at: Date.now(), value: settings };
55
+ return settings;
56
+ }
57
+ /** Sends what each destination has waiting. One that fails keeps its entries for next time, up to the limit. */
58
+ async function send(entries) {
59
+ await Promise.all(destinations.map(async (destination) => {
60
+ const pending = [...(state.retry.get(destination.name) ?? []), ...entries];
61
+ if (!pending.length)
62
+ return;
63
+ try {
64
+ await destination.write(pending);
65
+ state.retry.delete(destination.name);
66
+ }
67
+ catch (error) {
68
+ console.error(`[request-logs] couldn't send to ${destination.name}:`, error instanceof Error ? error.message : error);
69
+ state.retry.set(destination.name, pending.slice(-MAX_WAITING));
70
+ }
71
+ }));
72
+ }
73
+ /** Writes what's waiting. One write at a time per server. */
74
+ function flush(context) {
75
+ state.flushing ??= (async () => {
76
+ try {
77
+ while (state.waiting.length) {
78
+ const taken = state.waiting.splice(0);
79
+ const settings = await settingsOf(context);
80
+ if (!settings.enabled)
81
+ continue;
82
+ const entries = taken
83
+ .filter((entry) => kept(settings.which, entry) && !settings.skip.some((prefix) => entry.path === prefix || entry.path.startsWith(`${prefix.replace(/\/+$/, "")}/`)))
84
+ .map((entry) => ({ ...entry, ipAddress: settings.storeIp ? entry.ipAddress : null, userAgent: settings.storeUserAgent ? entry.userAgent : null }));
85
+ if (!entries.length)
86
+ continue;
87
+ if (settings.database) {
88
+ for (const batch of toBatches(entries)) {
89
+ await context.store.set(batchKey(batch[0].at, crypto.randomUUID().slice(0, 8)), batch).catch((error) => console.error("[request-logs] couldn't save entries:", error));
90
+ }
91
+ }
92
+ if (settings.destinations)
93
+ await send(entries);
94
+ }
95
+ if (state.dropped) {
96
+ console.warn(`[request-logs] dropped ${state.dropped} entries because too many were waiting`);
97
+ state.dropped = 0;
98
+ }
99
+ }
100
+ finally {
101
+ state.flushing = null;
102
+ }
103
+ })();
104
+ return state.flushing;
105
+ }
106
+ function onRequest(request, context) {
107
+ // The log's own page reading it isn't worth logging.
108
+ if (request.path === own || request.path.startsWith(`${own}/`))
109
+ return;
110
+ if (state.settings && !state.settings.value.enabled && Date.now() - state.settings.at < SETTINGS_TTL_MS)
111
+ return;
112
+ if (state.waiting.length >= MAX_WAITING) {
113
+ state.dropped += 1;
114
+ return;
115
+ }
116
+ state.waiting.push({ ...request, at: request.at.toISOString() });
117
+ state.timer ??= setTimeout(() => {
118
+ state.timer = null;
119
+ void flush(context).catch((error) => console.error("[request-logs]", error));
120
+ }, FLUSH_MS);
121
+ state.timer.unref?.();
122
+ }
123
+ return definePlugin({
124
+ name: NAME,
125
+ version: "0.1.1",
126
+ apiVersion: 1,
127
+ requires: { cms: "^0.1.1" },
128
+ admin: { server: "@tansy/request-logs/admin" },
129
+ options: { schema: optionsSchema, value },
130
+ messages,
131
+ permissions: { "ext.request-logs": ["read"] },
132
+ settings: { fields },
133
+ onRequest,
134
+ routes: [
135
+ defineRoute({
136
+ method: "GET",
137
+ path: "/entries",
138
+ access: "permission",
139
+ permission: PERMISSION,
140
+ query: z.object({
141
+ method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional(),
142
+ path: z.string().max(200).optional(),
143
+ status: z.enum(["2xx", "3xx", "4xx", "5xx"]).optional(),
144
+ before: z.string().startsWith(BATCH_PREFIX).max(200).optional(),
145
+ }),
146
+ handler: async (context) => {
147
+ // What this server still holds shows up straight away.
148
+ await flush(context).catch(() => undefined);
149
+ const settings = await settingsOf(context, { fresh: true });
150
+ const { method, path, status, before } = context.query;
151
+ const { items, next } = await findEntries((cursor, limit) => context.store.list(BATCH_PREFIX, { before: cursor, order: "desc", limit }), { method, path, status }, { before });
152
+ return {
153
+ items,
154
+ next,
155
+ enabled: settings.enabled,
156
+ database: settings.database,
157
+ destinations: settings.destinations ? destinations.map((destination) => destination.label) : [],
158
+ };
159
+ },
160
+ }),
161
+ ],
162
+ jobs: [
163
+ {
164
+ name: "request-logs.prune",
165
+ cron: "41 3 * * *",
166
+ handler: async (context) => {
167
+ const settings = await settingsOf(context, { fresh: true });
168
+ await context.store.deleteMany(BATCH_PREFIX, { before: cutoffKey(settings.retentionDays) });
169
+ },
170
+ },
171
+ ],
172
+ });
173
+ }
package/logic.d.ts ADDED
@@ -0,0 +1,56 @@
1
+ /** One logged request, as stored and as sent to destinations. */
2
+ export interface RequestLogEntry {
3
+ /** ISO 8601, in UTC. */
4
+ at: string;
5
+ method: string;
6
+ /** The path only. The query string can carry tokens, so it is never kept. */
7
+ path: string;
8
+ status: number;
9
+ durationMs: number;
10
+ actorId: string | null;
11
+ ipAddress: string | null;
12
+ userAgent: string | null;
13
+ }
14
+ export declare const WHICH: readonly ["all", "writes", "errors"];
15
+ export type Which = (typeof WHICH)[number];
16
+ /** "writes" keeps everything but reads that succeeded, "errors" only answers of 400 and up. */
17
+ export declare function kept(which: Which, entry: Pick<RequestLogEntry, "method" | "status">): boolean;
18
+ export declare const BATCH_PREFIX = "b:";
19
+ /** A few hundred entries: well under the store's 256 KiB a value, and a page the dashboard can show at once. */
20
+ export declare const MAX_BATCH_BYTES: number;
21
+ /** Keys sort by time, so the newest batch is the highest key. */
22
+ export declare const batchKey: (firstAt: string, suffix: string) => string;
23
+ /** Every key of a batch older than this many days sorts below the result. */
24
+ export declare const cutoffKey: (days: number, now?: number) => string;
25
+ /** Splits entries into batches that each fit in one stored value. */
26
+ export declare function toBatches(entries: RequestLogEntry[], maxBytes?: number): RequestLogEntry[][];
27
+ /** A stored batch, read defensively: anything that isn't an entry is skipped. */
28
+ export declare function readBatch(value: unknown): RequestLogEntry[];
29
+ export interface EntryFilter {
30
+ method?: string;
31
+ path?: string;
32
+ status?: "2xx" | "3xx" | "4xx" | "5xx";
33
+ }
34
+ export declare function matches(entry: RequestLogEntry, { method, path, status }: EntryFilter): boolean;
35
+ export type LoggedEntry = RequestLogEntry & {
36
+ id: string;
37
+ };
38
+ /**
39
+ * Reads batches newest first, from below `before` when given, until `perPage` entries match
40
+ * or `maxBatches` batches have been read. `next` continues from where it stopped, null at
41
+ * the oldest. `readPage` lists batches below a key, newest first.
42
+ */
43
+ export declare function findEntries(readPage: (before: string | undefined, limit: number) => Promise<Array<{
44
+ key: string;
45
+ value: unknown;
46
+ }>>, filter: EntryFilter, { before, perPage, maxBatches, pageSize }?: {
47
+ before?: string;
48
+ perPage?: number;
49
+ maxBatches?: number;
50
+ pageSize?: number;
51
+ }): Promise<{
52
+ items: LoggedEntry[];
53
+ next: string | null;
54
+ }>;
55
+ /** The paths never logged, as written in the settings: one prefix a line. */
56
+ export declare function skipList(text: unknown): string[];
package/logic.js ADDED
@@ -0,0 +1,84 @@
1
+ export const WHICH = ["all", "writes", "errors"];
2
+ /** "writes" keeps everything but reads that succeeded, "errors" only answers of 400 and up. */
3
+ export function kept(which, entry) {
4
+ if (which === "errors")
5
+ return entry.status >= 400;
6
+ if (which === "writes")
7
+ return entry.status >= 400 || !["GET", "HEAD", "OPTIONS"].includes(entry.method);
8
+ return true;
9
+ }
10
+ export const BATCH_PREFIX = "b:";
11
+ /** A few hundred entries: well under the store's 256 KiB a value, and a page the dashboard can show at once. */
12
+ export const MAX_BATCH_BYTES = 64 * 1024;
13
+ /** Keys sort by time, so the newest batch is the highest key. */
14
+ export const batchKey = (firstAt, suffix) => `${BATCH_PREFIX}${firstAt}:${suffix}`;
15
+ /** Every key of a batch older than this many days sorts below the result. */
16
+ export const cutoffKey = (days, now = Date.now()) => `${BATCH_PREFIX}${new Date(now - days * 86_400_000).toISOString()}`;
17
+ /** Splits entries into batches that each fit in one stored value. */
18
+ export function toBatches(entries, maxBytes = MAX_BATCH_BYTES) {
19
+ const batches = [];
20
+ let current = [];
21
+ let size = 2;
22
+ for (const entry of entries) {
23
+ const bytes = Buffer.byteLength(JSON.stringify(entry)) + 1;
24
+ if (current.length && size + bytes > maxBytes) {
25
+ batches.push(current);
26
+ current = [];
27
+ size = 2;
28
+ }
29
+ current.push(entry);
30
+ size += bytes;
31
+ }
32
+ if (current.length)
33
+ batches.push(current);
34
+ return batches;
35
+ }
36
+ /** A stored batch, read defensively: anything that isn't an entry is skipped. */
37
+ export function readBatch(value) {
38
+ if (!Array.isArray(value))
39
+ return [];
40
+ return value.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.at === "string" && typeof entry.method === "string" && typeof entry.path === "string" && typeof entry.status === "number");
41
+ }
42
+ export function matches(entry, { method, path, status }) {
43
+ if (method && entry.method !== method)
44
+ return false;
45
+ if (path && !entry.path.toLowerCase().includes(path.toLowerCase()))
46
+ return false;
47
+ if (status) {
48
+ const floor = Number(status[0]) * 100;
49
+ if (entry.status < floor || entry.status >= floor + 100)
50
+ return false;
51
+ }
52
+ return true;
53
+ }
54
+ /**
55
+ * Reads batches newest first, from below `before` when given, until `perPage` entries match
56
+ * or `maxBatches` batches have been read. `next` continues from where it stopped, null at
57
+ * the oldest. `readPage` lists batches below a key, newest first.
58
+ */
59
+ export async function findEntries(readPage, filter, { before, perPage = 50, maxBatches = 200, pageSize = 20 } = {}) {
60
+ const items = [];
61
+ let cursor = before;
62
+ let read = 0;
63
+ while (read < maxBatches) {
64
+ const limit = Math.min(pageSize, maxBatches - read);
65
+ const batches = await readPage(cursor, limit);
66
+ for (const [index, { key, value }] of batches.entries()) {
67
+ readBatch(value).forEach((entry, position) => { if (matches(entry, filter))
68
+ items.push({ ...entry, id: `${key}#${position}` }); });
69
+ cursor = key;
70
+ read += 1;
71
+ const more = index < batches.length - 1 || batches.length === limit;
72
+ if (items.length >= perPage)
73
+ return { items: newestFirst(items), next: more ? cursor : null };
74
+ }
75
+ if (batches.length < limit)
76
+ return { items: newestFirst(items), next: null };
77
+ }
78
+ return { items: newestFirst(items), next: cursor ?? null };
79
+ }
80
+ const newestFirst = (items) => items.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0));
81
+ /** The paths never logged, as written in the settings: one prefix a line. */
82
+ export function skipList(text) {
83
+ return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith("/"));
84
+ }
package/messages.d.ts ADDED
@@ -0,0 +1,143 @@
1
+ /** The request-logs plugin's dashboard words, read as `t("ext.request-logs.<key>")`. */
2
+ export declare const messages: {
3
+ en: {
4
+ section: string;
5
+ pages: {
6
+ "request-logs": string;
7
+ };
8
+ description: string;
9
+ settings: {
10
+ enabled: {
11
+ label: string;
12
+ description: string;
13
+ };
14
+ which: {
15
+ label: string;
16
+ description: string;
17
+ options: {
18
+ all: string;
19
+ writes: string;
20
+ errors: string;
21
+ };
22
+ };
23
+ database: {
24
+ label: string;
25
+ description: string;
26
+ };
27
+ destinations: {
28
+ label: string;
29
+ description: string;
30
+ };
31
+ storeIp: {
32
+ label: string;
33
+ description: string;
34
+ };
35
+ storeUserAgent: {
36
+ label: string;
37
+ description: string;
38
+ };
39
+ skip: {
40
+ label: string;
41
+ description: string;
42
+ };
43
+ retentionDays: {
44
+ label: string;
45
+ description: string;
46
+ };
47
+ };
48
+ tabs: {
49
+ logs: string;
50
+ settings: string;
51
+ };
52
+ path: string;
53
+ method: string;
54
+ status: string;
55
+ time: string;
56
+ ip: string;
57
+ when: string;
58
+ ms: string;
59
+ filterPath: string;
60
+ filterMethod: string;
61
+ filterStatus: string;
62
+ allMethods: string;
63
+ allStatuses: string;
64
+ older: string;
65
+ newest: string;
66
+ empty: string;
67
+ noMatches: string;
68
+ off: string;
69
+ notHere: string;
70
+ sentTo: string;
71
+ failed: string;
72
+ };
73
+ ar: {
74
+ section: string;
75
+ pages: {
76
+ "request-logs": string;
77
+ };
78
+ description: string;
79
+ settings: {
80
+ enabled: {
81
+ label: string;
82
+ description: string;
83
+ };
84
+ which: {
85
+ label: string;
86
+ description: string;
87
+ options: {
88
+ all: string;
89
+ writes: string;
90
+ errors: string;
91
+ };
92
+ };
93
+ database: {
94
+ label: string;
95
+ description: string;
96
+ };
97
+ destinations: {
98
+ label: string;
99
+ description: string;
100
+ };
101
+ storeIp: {
102
+ label: string;
103
+ description: string;
104
+ };
105
+ storeUserAgent: {
106
+ label: string;
107
+ description: string;
108
+ };
109
+ skip: {
110
+ label: string;
111
+ description: string;
112
+ };
113
+ retentionDays: {
114
+ label: string;
115
+ description: string;
116
+ };
117
+ };
118
+ tabs: {
119
+ logs: string;
120
+ settings: string;
121
+ };
122
+ path: string;
123
+ method: string;
124
+ status: string;
125
+ time: string;
126
+ ip: string;
127
+ when: string;
128
+ ms: string;
129
+ filterPath: string;
130
+ filterMethod: string;
131
+ filterStatus: string;
132
+ allMethods: string;
133
+ allStatuses: string;
134
+ older: string;
135
+ newest: string;
136
+ empty: string;
137
+ noMatches: string;
138
+ off: string;
139
+ notHere: string;
140
+ sentTo: string;
141
+ failed: string;
142
+ };
143
+ };
package/messages.js ADDED
@@ -0,0 +1,75 @@
1
+ /** The request-logs plugin's dashboard words, read as `t("ext.request-logs.<key>")`. */
2
+ export const messages = {
3
+ en: {
4
+ section: "Request logs",
5
+ pages: { "request-logs": "Request logs" },
6
+ description: "Every API request, with its answer and how long it took.",
7
+ settings: {
8
+ enabled: { label: "Log API requests", description: "When off, nothing new is logged anywhere." },
9
+ which: { label: "Which requests", description: "Reads that worked are most of them, and the least useful.", options: { all: "All of them", writes: "Changes and errors", errors: "Errors only" } },
10
+ database: { label: "Keep them in the database", description: "Shown on this page. Turn it off to send them only to the places below." },
11
+ destinations: { label: "Also send them outside", description: "To the places set up in the site's code, such as S3 or a log service, a few seconds' worth at a time. The Logs tab names them." },
12
+ storeIp: { label: "Keep IP addresses", description: "Off leaves them out, for privacy." },
13
+ storeUserAgent: { label: "Keep browsers", description: "The user agent each request sent. Off leaves it out." },
14
+ skip: { label: "Addresses not to log", description: "One per line, such as /api/realtime. Each covers everything under it." },
15
+ retentionDays: { label: "Keep entries here for (days)", description: "Older entries are deleted each night. Places outside keep them as long as they're set to." },
16
+ },
17
+ tabs: { logs: "Logs", settings: "Settings" },
18
+ path: "Path",
19
+ method: "Method",
20
+ status: "Status",
21
+ time: "Time",
22
+ ip: "IP",
23
+ when: "When",
24
+ ms: "{ms} ms",
25
+ filterPath: "Filter by path",
26
+ filterMethod: "Filter by method",
27
+ filterStatus: "Filter by status",
28
+ allMethods: "All methods",
29
+ allStatuses: "All statuses",
30
+ older: "Older",
31
+ newest: "Newest",
32
+ empty: "No requests logged yet.",
33
+ noMatches: "No requests match.",
34
+ off: "Logging is off. Nothing new is recorded.",
35
+ notHere: "Requests aren't kept in the database, so none show here.",
36
+ sentTo: "Also sent to {destinations}.",
37
+ failed: "The log couldn't be read.",
38
+ },
39
+ ar: {
40
+ section: "سجلات الطلبات",
41
+ pages: { "request-logs": "سجلات الطلبات" },
42
+ description: "كل طلب للواجهة البرمجية، مع الرد عليه والمدة التي استغرقها.",
43
+ settings: {
44
+ enabled: { label: "سجّل طلبات الواجهة البرمجية", description: "عند الإيقاف لا يُسجَّل شيء جديد في أي مكان." },
45
+ which: { label: "أي الطلبات", description: "القراءات الناجحة هي أغلبها وأقلها فائدة.", options: { all: "كلها", writes: "التغييرات والأخطاء", errors: "الأخطاء فقط" } },
46
+ database: { label: "احفظها في قاعدة البيانات", description: "تظهر في هذه الصفحة. أوقفها لإرسالها فقط إلى الأماكن أدناه." },
47
+ destinations: { label: "أرسلها أيضًا إلى الخارج", description: "إلى الأماكن المضبوطة في شيفرة الموقع، مثل S3 أو خدمة سجلات، بضع ثوانٍ منها في كل مرة. تبويب السجلات يذكرها." },
48
+ storeIp: { label: "احفظ عناوين IP", description: "الإيقاف يتركها خارج السجل، حفاظًا على الخصوصية." },
49
+ storeUserAgent: { label: "احفظ المتصفحات", description: "وكيل المستخدم الذي أرسله كل طلب. الإيقاف يتركه خارج السجل." },
50
+ skip: { label: "عناوين لا تُسجَّل", description: "عنوان في كل سطر، مثل /api/realtime. يشمل كل عنوان ما تحته." },
51
+ retentionDays: { label: "احتفظ بالإدخالات هنا لمدة (أيام)", description: "تُحذف الإدخالات الأقدم كل ليلة. الأماكن الخارجية تحتفظ بها حسب إعدادها." },
52
+ },
53
+ tabs: { logs: "السجلات", settings: "الإعدادات" },
54
+ path: "المسار",
55
+ method: "الطريقة",
56
+ status: "الحالة",
57
+ time: "المدة",
58
+ ip: "IP",
59
+ when: "الوقت",
60
+ ms: "{ms} مللي ثانية",
61
+ filterPath: "تصفية حسب المسار",
62
+ filterMethod: "تصفية حسب الطريقة",
63
+ filterStatus: "تصفية حسب الحالة",
64
+ allMethods: "كل الطرق",
65
+ allStatuses: "كل الحالات",
66
+ older: "الأقدم",
67
+ newest: "الأحدث",
68
+ empty: "لم يُسجَّل أي طلب بعد.",
69
+ noMatches: "لا طلبات مطابقة.",
70
+ off: "التسجيل متوقف. لا يُسجَّل شيء جديد.",
71
+ notHere: "لا تُحفظ الطلبات في قاعدة البيانات، لذلك لا يظهر شيء هنا.",
72
+ sentTo: "تُرسل أيضًا إلى {destinations}.",
73
+ failed: "تعذرت قراءة السجل.",
74
+ },
75
+ };
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "@tansy/request-logs",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "A log of every API request for tansy: kept in the database and shown on the dashboard, sent to S3 or any storage, an HTTP log drain, or the console, or all of them.",
5
+ "keywords": [
6
+ "tansy",
7
+ "tansy-plugin",
8
+ "cms",
9
+ "nextjs"
10
+ ],
11
+ "license": "MIT",
12
+ "author": "Mohamed Salah <mohamedsalahsebai@gmail.com>",
13
+ "homepage": "https://github.com/mhmdsalahsebai/tansy",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/mhmdsalahsebai/tansy.git",
17
+ "directory": "plugins/request-logs"
18
+ },
19
+ "bugs": "https://github.com/mhmdsalahsebai/tansy/issues",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./index.d.ts",
23
+ "default": "./index.js"
24
+ },
25
+ "./admin": {
26
+ "types": "./admin.d.ts",
27
+ "default": "./admin.js"
28
+ }
29
+ },
30
+ "peerDependencies": {
31
+ "next": "^16.4.6",
32
+ "react": "^19.3.0",
33
+ "tansy": "^0.1.1"
34
+ },
35
+ "dependencies": {
36
+ "zod": "^4.6.7"
37
+ }
38
+ }
package/view.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ /** Newest first, a page at a time: "Older" follows the cursor, and "Newest" goes back to the start. */
2
+ export declare function RequestLogView(): import("react").JSX.Element;
package/view.js ADDED
@@ -0,0 +1,54 @@
1
+ "use client";
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { useEffect, useState } from "react";
4
+ import { Alert, apiPath, Badge, Button, DataTable, SearchInput, Toolbar, useT } from "tansy/admin";
5
+ const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
6
+ const STATUSES = ["2xx", "3xx", "4xx", "5xx"];
7
+ const SELECT = "cms-input cms-input-auto";
8
+ const statusTone = (status) => (status >= 500 ? "danger" : status >= 400 ? "warning" : "success");
9
+ /** Newest first, a page at a time: "Older" follows the cursor, and "Newest" goes back to the start. */
10
+ export function RequestLogView() {
11
+ const { t: translate, locale } = useT();
12
+ const t = (key, values) => translate(`ext.request-logs.${key}`, values);
13
+ const [path, setPath] = useState("");
14
+ const [method, setMethod] = useState("");
15
+ const [status, setStatus] = useState("");
16
+ const [cursors, setCursors] = useState([]);
17
+ const [answer, setAnswer] = useState(null);
18
+ const [failed, setFailed] = useState(false);
19
+ const before = cursors.at(-1);
20
+ useEffect(() => {
21
+ let live = true;
22
+ const query = new URLSearchParams();
23
+ if (path)
24
+ query.set("path", path);
25
+ if (method)
26
+ query.set("method", method);
27
+ if (status)
28
+ query.set("status", status);
29
+ if (before)
30
+ query.set("before", before);
31
+ fetch(apiPath(`/ext/request-logs/entries?${query}`), { cache: "no-store" })
32
+ .then((response) => (response.ok ? response.json() : Promise.reject(new Error(String(response.status)))))
33
+ .then((value) => { if (live) {
34
+ setAnswer(value);
35
+ setFailed(false);
36
+ } })
37
+ .catch(() => { if (live)
38
+ setFailed(true); });
39
+ return () => { live = false; };
40
+ }, [path, method, status, before]);
41
+ const filter = (set) => (value) => { set(value); setCursors([]); };
42
+ const filtered = Boolean(path || method || status);
43
+ return (_jsxs("div", { className: "cms-stack-4", children: [failed && _jsx(Alert, { children: t("failed") }), answer && !answer.enabled && _jsx(Alert, { kind: "warning", children: t("off") }), answer?.enabled && !answer.database && _jsx(Alert, { kind: "info", children: t("notHere") }), answer && answer.destinations.length > 0 && _jsx("p", { className: "cms-hint", children: t("sentTo", { destinations: answer.destinations.join(", ") }) }), _jsx(DataTable, { label: t("pages.request-logs"), columns: [{ id: "path", label: t("path") }, { id: "method", label: t("method") }, { id: "status", label: t("status") }, { id: "time", label: t("time"), numeric: true }, { id: "ip", label: t("ip") }, { id: "when", label: t("when") }], rows: answer ? answer.items.map((entry) => ({
44
+ id: entry.id,
45
+ cells: {
46
+ path: _jsx("span", { className: "cms-mono cms-text-xs", children: entry.path }),
47
+ method: _jsx("span", { className: "cms-mono cms-text-xs", children: entry.method }),
48
+ status: _jsx(Badge, { tone: statusTone(entry.status), children: entry.status }),
49
+ time: t("ms", { ms: entry.durationMs.toLocaleString(locale) }),
50
+ ip: entry.ipAddress,
51
+ when: _jsx("span", { className: "cms-nowrap", children: new Date(entry.at).toLocaleString(locale) }),
52
+ },
53
+ })) : null, toolbar: (_jsxs(Toolbar, { children: [_jsx(SearchInput, { "aria-label": t("filterPath"), placeholder: t("filterPath"), value: path, onChange: (event) => filter(setPath)(event.target.value) }), _jsxs("select", { "aria-label": t("filterMethod"), className: SELECT, value: method, onChange: (event) => filter(setMethod)(event.target.value), children: [_jsx("option", { value: "", children: t("allMethods") }), METHODS.map((name) => _jsx("option", { value: name, children: name }, name))] }), _jsxs("select", { "aria-label": t("filterStatus"), className: SELECT, value: status, onChange: (event) => filter(setStatus)(event.target.value), children: [_jsx("option", { value: "", children: t("allStatuses") }), STATUSES.map((name) => _jsx("option", { value: name, children: name }, name))] })] })), empty: { title: filtered ? t("noMatches") : t("empty") }, footer: answer && (cursors.length > 0 || answer.next) ? (_jsxs("div", { className: "cms-row cms-gap-2", children: [_jsx(Button, { variant: "secondary", disabled: !cursors.length, onClick: () => setCursors([]), children: t("newest") }), _jsx(Button, { variant: "secondary", disabled: !answer.next, onClick: () => answer.next && setCursors([...cursors, answer.next]), children: t("older") })] })) : undefined })] }));
54
+ }