feat: implement log route (#38)

Author: dominique-pfister

src/index.js

@@ -21,6 +21,7 @@ import contentproxy from './contentproxy/handler.js';
 import discover from './discover/handler.js';
 import index from './index/handler.js';
 import live from './live/handler.js';
+import log from './log/handler.js';
 import { auth, login, logout } from './login/handler.js';
 import media from './media/handler.js';
 import preview from './preview/handler.js';
@@ -81,6 +82,7 @@ export const router = new Router(nameSelector)
   .add('/:org/sites/:site/contentproxy/*', contentproxy)
   .add('/:org/sites/:site/preview/*', preview)
   .add('/:org/sites/:site/live/*', live)
+  .add('/:org/sites/:site/log', log)
   .add('/:org/sites/:site/login', login)
   .add('/:org/sites/:site/media/*', media)
   .add('/:org/sites/:site/code/:ref/*', code)
@@ -89,8 +91,7 @@ export const router = new Router(nameSelector)
   .add('/:org/sites/:site/sitemap/*', sitemap)
   .add('/:org/sites/:site/snapshots/*', notImplemented)
   .add('/:org/sites/:site/source/*', notImplemented)
-  .add('/:org/sites/:site/jobs', notImplemented)
-  .add('/:org/sites/:site/log', notImplemented);
+  .add('/:org/sites/:site/jobs', notImplemented);
 
 /**
  * Main entry point.

src/log/DateFormat.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+export default class DateFormat {
+  static parse(s) {
+    const chars = [...s.substring(0, 19)];
+    chars[10] = 'T';
+    chars[13] = ':';
+    chars[16] = ':';
+    chars.push('Z');
+    return new Date(chars.join(''));
+  }
+
+  static format(date) {
+    return date.toISOString().substring(0, 19).replace(/[T:]/g, '-');
+  }
+}

src/log/add.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { Response } from '@adobe/fetch';
+import { errorResponse } from '../support/utils.js';
+import { AuditBatch } from '../support/audit.js';
+
+/**
+ * Add entries to an audit log.
+ *
+ * @param {import('./AdminContext.js').AdminContext} context context
+ * @param {import('./RequestInfo.js').RequestInfo} info request info
+ *
+ * @returns {Promise<Response>} response
+ */
+export default async function add(context, info) {
+  const { attributes: { authInfo }, contentBusId, log } = context;
+
+  const { data: { entries } } = context;
+  if (!entries || !Array.isArray(entries)) {
+    return errorResponse(log, 400, 'Adding logs requires an array in \'entries\'');
+  }
+  if (entries.length > 10) {
+    return errorResponse(log, 400, 'Array in \'entries\' should not contain more than 10 messages');
+  }
+
+  const batch = new AuditBatch(info);
+  const user = authInfo.resolveEmail();
+
+  entries.forEach((entry) => {
+    const notification = {
+      ...entry,
+      timestamp: Date.now(),
+    };
+    if (contentBusId) {
+      notification.contentBusId = contentBusId;
+    }
+    if (user) {
+      notification.user = user;
+    }
+    batch.addNotification(info, notification);
+  });
+  await batch.send(context);
+
+  return new Response('', {
+    status: 201,
+    headers: {
+      'content-type': 'text/plain; charset=utf-8',
+    },
+  });
+}

src/log/handler.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { Response } from '@adobe/fetch';
+import add from './add.js';
+import query from './query.js';
+
+/**
+ * Allowed methods for that handler
+ */
+const ALLOWED_METHODS = ['GET', 'POST'];
+
+/**
+ * Handles the log route
+ *
+ * @param {import('../support/AdminContext').AdminContext} context context
+ * @param {import('../support/RequestInfo').RequestInfo} info request info
+ * @returns {Promise<Response>} response
+ */
+export default async function logHandler(context, info) {
+  const { attributes: { authInfo } } = context;
+
+  if (ALLOWED_METHODS.indexOf(info.method) < 0) {
+    return new Response('method not allowed', {
+      status: 405,
+    });
+  }
+
+  authInfo.assertPermissions('log:read');
+  if (info.method === 'GET') {
+    return query(context, info);
+  }
+
+  authInfo.assertPermissions('log:write');
+  return add(context, info);
+}

src/log/query.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { Response } from '@adobe/fetch';
+import { AuditLog } from '@adobe/helix-admin-support';
+import { errorResponse } from '../support/utils.js';
+import {
+  decode, encode, getNextLinkUrl, parseIntWithCond, parseTimespan,
+} from './utils.js';
+
+/**
+ * Total size of collected entries in log, when stringified.
+ */
+export const MAX_ENTRIES_SIZE = 3_000_000;
+
+/**
+ * Query an audit log
+ *
+ * @param {import('./AdminContext.js').AdminContext} context context
+ * @param {import('./RequestInfo.js').RequestInfo} info request info
+ * @returns {Promise<Response>} response
+ */
+export default async function query(context, info) {
+  const {
+    log, data: {
+      from: fromS, to: toS, since: sinceS, limit: limitS, nextToken,
+    },
+  } = context;
+
+  let from;
+  let to;
+
+  try {
+    ([from, to] = parseTimespan(fromS, toS, sinceS));
+  } catch (e) {
+    return errorResponse(log, 400, e.message);
+  }
+
+  const limit = parseIntWithCond(limitS, (value) => {
+    if (value >= 1 && value <= 1000) {
+      return true;
+    }
+    log.warn(`'limit' should be between 1 and 1000: ' ${value}`);
+    return false;
+  }, 1000);
+
+  const { org, site } = info;
+  const auditLog = AuditLog.createReader(org, site, log);
+
+  try {
+    await auditLog.init();
+
+    const { entries, next } = await auditLog.getEntries(
+      from,
+      to,
+      { limit, maxSize: MAX_ENTRIES_SIZE },
+      decode(nextToken),
+    );
+    const result = {
+      from: new Date(from).toISOString(),
+      to: new Date(to).toISOString(),
+      entries,
+    };
+    if (next) {
+      result.nextToken = encode(next);
+      result.links = {
+        next: getNextLinkUrl(info, {
+          from: result.from,
+          to: result.to,
+          limit: limitS,
+          nextToken: result.nextToken,
+        }),
+      };
+    }
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: {
+        'content-type': 'application/json',
+      },
+    });
+  } finally {
+    auditLog.close();
+  }
+}

src/log/utils.js

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export function decode(nextToken) {
+  try {
+    if (nextToken) {
+      return JSON.parse(Buffer.from(nextToken, 'base64'));
+    }
+  } catch (e) {
+    /* ignore */
+  }
+  return null;
+}
+
+export function encode(next) {
+  return Buffer.from(JSON.stringify(next)).toString('base64');
+}
+
+export function parseIntWithCond(s, cond, defaultValue) {
+  if (s) {
+    const value = Number.parseInt(s, 10);
+    if (!Number.isNaN(value) && cond(value)) {
+      return value;
+    }
+  }
+  return defaultValue;
+}
+
+export function getNextLinkUrl(info, query) {
+  return info.getLinkUrl(info.suffix, Object.entries(query).reduce((o, [k, v]) => {
+    if (v) {
+      // eslint-disable-next-line no-param-reassign
+      o[k] = v;
+    }
+    return o;
+  }, {}));
+}
+
+const UNITS = {
+  s: (v) => v,
+  m: (v) => v * 60,
+  h: (v) => v * 3600,
+  d: (v) => v * 3600 * 24,
+};
+
+const FIFTEEN_MINUTES_MS = 15 * 60 * 1000;
+
+export function parseTimespan(fromS, toS, sinceS) {
+  const now = Date.now();
+
+  if (sinceS) {
+    if (fromS || toS) {
+      throw new Error('\'since\' should not be used with either \'from\' or \'to\'');
+    }
+    const match = /^(?<duration>[0-9]+)(?<unit>s|m|h|d)$/.exec(sinceS);
+    if (!match) {
+      throw new Error(`'since' should match a number followed by 's(econds)', 'm(inutes)', 'h(ours)' or 'd(ays)': ${sinceS}`);
+    }
+    const { duration, unit } = match.groups;
+    const sinceMs = UNITS[unit](Number.parseInt(duration, 10)) * 1000;
+    return [now - sinceMs, now];
+  }
+
+  let from;
+  if (!fromS) {
+    from = now - FIFTEEN_MINUTES_MS;
+  } else {
+    from = Date.parse(fromS);
+    if (!from) {
+      throw new Error(`'from' is not a valid date: ${fromS}`);
+    }
+  }
+  let to;
+  if (!toS) {
+    to = now;
+  } else {
+    to = Date.parse(toS);
+    if (!to) {
+      throw new Error(`'to' is not a valid date: ${toS}`);
+    }
+  }
+  if (from >= to) {
+    throw new Error(`'from' (${fromS || new Date(from).toISOString()}) should be smaller than 'to' (${toS || new Date(to).toISOString()})`);
+  }
+  return [from, to];
+}