fix: make /aggregate execute before datasource request hooks

Author: yaroslav8765

adminforth/modules/restApi.ts

@@ -1889,14 +1889,14 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
     server.endpoint({
       method: 'POST',
       path: '/aggregate',
-      description: 'Performs aggregation queries (sum, count, avg, min, max, median) on a resource, with optional grouping by field value or date truncation. Requires list and show access to the resource, and only accepts columns the user can read on the show view: backend-only columns and columns hidden from the show view are rejected.',
+      description: 'Performs aggregation queries (sum, count, avg, min, max, median) on a resource, with optional grouping by field value or date truncation. Requires list and show access to the resource, and only accepts columns the user can read on the show view: backend-only columns and columns hidden from the show view are rejected. Runs the resource list.beforeDatasourceRequest and list.afterDatasourceResponse hooks.',
       agent: {
         onlyReadsData: true,
       },
       request_schema: aggregateRequestSchema,
       response_schema: aggregateResponseSchema,
-      handler: async ({ body, adminUser, headers }) => {
-        const { resourceId, aggregations, filters, groupBy } = body;
+      handler: async ({ body, adminUser, headers, query, cookies, requestUrl }) => {
+        const { resourceId } = body;
         if (!this.adminforth.statuses.dbDiscover) {
           return { error: 'Database discovery not started' };
         }
@@ -1907,7 +1907,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         if (!resource) {
           return { error: `Resource ${resourceId} not found` };
         }
-        const rawFilterError = rejectApiRawFilters(filters);
+        const rawFilterError = rejectApiRawFilters(body.filters);
         if (rawFilterError) {
           return rawFilterError;
         }
@@ -1966,7 +1966,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           return null;
         };
 
-        for (const [alias, rule] of Object.entries((aggregations || {}) as { [alias: string]: IAggregationRule })) {
+        for (const [alias, rule] of Object.entries((body.aggregations || {}) as { [alias: string]: IAggregationRule })) {
           // plain count does not reference any column
           if (!rule?.field) {
             continue;
@@ -1977,7 +1977,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           }
         }
 
-        const groupByRules = Array.isArray(groupBy) ? groupBy : (groupBy ? [groupBy] : []);
+        const groupByRules = Array.isArray(body.groupBy) ? body.groupBy : (body.groupBy ? [body.groupBy] : []);
         for (const groupByRule of groupByRules) {
           if (!groupByRule?.field) {
             continue;
@@ -1988,11 +1988,32 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           }
         }
 
-        const backendOnlyFilterError = await rejectBackendOnlyFilters(filters, columnCtx);
+        const backendOnlyFilterError = await rejectBackendOnlyFilters(body.filters, columnCtx);
         if (backendOnlyFilterError) {
           return backendOnlyFilterError;
         }
 
+        // aggregation reads the same set of records as the list, so the list hooks scope it
+        for (const hook of listify(resource.hooks?.list?.beforeDatasourceRequest as BeforeDataSourceRequestFunction[])) {
+          const filterTools = filtersTools.get(body);
+          body.filtersTools = filterTools;
+          const resp = await (hook as BeforeDataSourceRequestFunction)({
+            resource,
+            query: body,
+            adminUser,
+            filtersTools: filterTools,
+            extra: {
+              body, query, headers, cookies, requestUrl
+            },
+            adminforth: this.adminforth,
+          });
+          const hookRespError = hookResponseError(resp);
+          if (hookRespError) {
+            return hookRespError;
+          }
+        }
+        const { aggregations, filters, groupBy } = body;
+
         // normalize filters same way as get_resource_data
         const normalizedFilters = { operator: AdminForthFilterOperators.AND, subFilters: [] };
         if (filters) {
@@ -2011,25 +2032,45 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           }
         }
 
+        const userTimeZone = headers['X-TimeZone'];
+        const applyUserTimeZone = (groupByRule: any) => groupByRule?.type === 'date_trunc' && userTimeZone
+          ? { ...groupByRule, timezone: userTimeZone }
+          : groupByRule;
+        const aggregateGroupBy = Array.isArray(groupBy)
+          ? groupBy.map(applyUserTimeZone)
+          : applyUserTimeZone(groupBy);
+
+        let data;
         try {
-          const userTimeZone = headers['X-TimeZone'];
-          const applyUserTimeZone = (groupByRule: any) => groupByRule?.type === 'date_trunc' && userTimeZone
-            ? { ...groupByRule, timezone: userTimeZone }
-            : groupByRule;
-          const aggregateGroupBy = Array.isArray(groupBy)
-            ? groupBy.map(applyUserTimeZone)
-            : applyUserTimeZone(groupBy);
-
-          const data = await this.adminforth.connectors[resource.dataSource].aggregate({
+          data = await this.adminforth.connectors[resource.dataSource].aggregate({
             resource,
             filters: normalizedFilters as IAdminForthAndOrFilter,
             aggregations,
             groupBy: aggregateGroupBy,
           });
-          return { data };
         } catch (e) {
           return { error: e.message };
         }
+
+        // hooks get the aggregation rows as response, they can tell this call by query.aggregations
+        for (const hook of listify(resource.hooks?.list?.afterDatasourceResponse)) {
+          const resp = await hook({
+            resource,
+            query: body,
+            response: data,
+            adminUser,
+            extra: {
+              body, query, headers, cookies, requestUrl
+            },
+            adminforth: this.adminforth,
+          });
+          const hookRespError = hookResponseError(resp);
+          if (hookRespError) {
+            return hookRespError;
+          }
+        }
+
+        return { data };
       },
     });
 

documentation/docs/tutorial/03-Customization/04-hooks.md

@@ -205,6 +205,34 @@ When you enrich records with extra fields for display, declare a matching [virtu
 Reusing the same name keeps the enriched value tied to a column the rest of AdminForth knows about. In particular, the [Agent plugin](/docs/tutorial/Plugins/agent/) selects records by column name when answering questions — if the hook writes to a different field than the virtual column, the agent selects the (empty) virtual column and never sees your enriched value.
 :::
 
+### Aggregations
+
+The `aggregate` API, which agents and [MCP clients](/docs/tutorial/Plugins/mcp/) use for counts, sums and other statistics, reads the same records as the list, so it runs the same `list.beforeDatasourceRequest` and `list.afterDatasourceResponse` hooks. Filters added in `list.beforeDatasourceRequest`, like the `realtor_id` filter above, limit aggregations too, so a user can't count or sum records the list hides from them.
+
+`list.afterDatasourceResponse` gets aggregation rows in `response` instead of records, for example `[{ group: 'Kyiv', total: 12 }]`. If your hook changes record fields, skip aggregation requests, they are the only ones with `query.aggregations`:
+
+```ts title='./resources/apartments.ts'
+{
+  ...
+  hooks: {
+    list: {
+      afterDatasourceResponse: async ({ query, response }: { query: any, response: any }) => {
+//diff-add
+        if (query.aggregations) {
+//diff-add
+          return { ok: true };
+//diff-add
+        }
+        response.forEach((r: any) => {
+          r.price = `$${r.price}`;
+        });
+        return { ok: true };
+      },
+    },
+  },
+}
+```
+
 ### Dropdown list of foreignResource
 
 By default if there is `foreignResource` like we use for demo on `realtor_id` column, the filter will suggest a

tests/application/pnpm-lock.yaml

@@ -0,0 +1,148 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const applicationDir = path.resolve(currentDir, '../application');
+
+// resolves to the BUILT package (adminforth/dist) the test application runs on;
+// rebuild it (`npx tsc` in adminforth/) after editing adminforth sources or the assertions below test stale code
+const require = createRequire(import.meta.url);
+// jest's resolver does not know the `node:sqlite` builtin, so it is required directly
+const { DatabaseSync } = require('node:sqlite');
+const adminforthEntry = require.resolve('adminforth', { paths: [applicationDir] });
+const { default: AdminForth } = await import(pathToFileURL(adminforthEntry).href);
+
+const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'af-aggregate-hooks-'));
+const dbPath = path.join(fixtureDir, 'db.sqlite');
+const db = new DatabaseSync(dbPath);
+db.exec(`
+  CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL, password_hash TEXT NOT NULL);
+  CREATE TABLE orders (id INTEGER PRIMARY KEY, owner TEXT NOT NULL, amount INTEGER NOT NULL);
+  INSERT INTO orders VALUES (1, 'alice', 10);
+  INSERT INTO orders VALUES (2, 'alice', 20);
+  INSERT INTO orders VALUES (3, 'bob', 5);
+`);
+db.close();
+
+process.env.ADMINFORTH_SECRET ??= 'x'.repeat(64);
+
+const afterHookCalls: { query: any, response: any }[] = [];
+
+delete (globalThis as any).adminforth;
+const app = new AdminForth({
+  baseUrl: '',
+  auth: {
+    usersResourceId: 'users',
+    usernameField: 'email',
+    passwordHashField: 'password_hash',
+  },
+  dataSources: [{ id: 'sqlite', url: `sqlite://${dbPath}` }],
+  resources: [
+    {
+      resourceId: 'users',
+      table: 'users',
+      dataSource: 'sqlite',
+      columns: [
+        { name: 'id', primaryKey: true },
+        { name: 'email' },
+        { name: 'password_hash', backendOnly: true },
+      ],
+    },
+    {
+      resourceId: 'orders',
+      table: 'orders',
+      dataSource: 'sqlite',
+      columns: [
+        { name: 'id', primaryKey: true },
+        { name: 'owner' },
+        { name: 'amount' },
+      ],
+      hooks: {
+        list: {
+          beforeDatasourceRequest: async ({ query, adminUser }) => {
+            if (adminUser.dbUser.role === 'blocked') {
+              return { ok: false, error: 'Blocked by hook' };
+            }
+            if (adminUser.dbUser.role !== 'superadmin') {
+              query.filtersTools.replaceOrAddTopFilter({ field: 'owner', operator: 'eq', value: adminUser.username });
+            }
+            return { ok: true };
+          },
+          afterDatasourceResponse: async ({ query, response }) => {
+            afterHookCalls.push({ query, response });
+            if (query.aggregations) {
+              for (const row of response) {
+                row.currency = 'USD';
+              }
+            }
+            return { ok: true };
+          },
+        },
+      },
+    },
+  ],
+  menu: [{ label: 'Orders', resourceId: 'orders' }],
+});
+await app.discoverDatabases();
+
+const endpoints: any[] = [];
+app.restApi.registerEndpoints({ endpoint: (config: any) => endpoints.push(config) });
+
+beforeEach(() => {
+  afterHookCalls.length = 0;
+});
+
+afterAll(() => {
+  rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+function aggregate(body: Record<string, unknown>, username: string, role = 'admin') {
+  const { handler } = endpoints.find((endpoint) => endpoint.path === '/aggregate');
+  return handler({
+    body: { resourceId: 'orders', ...body },
+    adminUser: { pk: '1', username, dbUser: { role } },
+    headers: {},
+    query: {},
+    cookies: {},
+    requestUrl: '/aggregate',
+    abortSignal: new AbortController().signal,
+  });
+}
+
+const totals = { aggregations: { orders: { operation: 'count' }, revenue: { operation: 'sum', field: 'amount' } } };
+
+describe('aggregate list hooks', () => {
+  it('scopes rows with filters added by list.beforeDatasourceRequest', async () => {
+    expect((await aggregate(totals, 'alice')).data).toEqual([
+      { orders: 2, revenue: 30, currency: 'USD' },
+    ]);
+    expect((await aggregate(totals, 'root', 'superadmin')).data).toEqual([
+      { orders: 3, revenue: 35, currency: 'USD' },
+    ]);
+  });
+
+  it('applies hook filters on top of the request filters and groupBy', async () => {
+    const result = await aggregate({
+      ...totals,
+      filters: [{ field: 'amount', operator: 'gt', value: 10 }],
+      groupBy: { type: 'field', field: 'owner', as: 'owner' },
+    }, 'alice');
+    expect(result.data).toEqual([{ owner: 'alice', orders: 1, revenue: 20, currency: 'USD' }]);
+  });
+
+  it('stops when list.beforeDatasourceRequest returns an error', async () => {
+    expect(await aggregate(totals, 'alice', 'blocked')).toEqual({ error: 'Blocked by hook' });
+    expect(afterHookCalls).toEqual([]);
+  });
+
+  it('passes the request and the aggregation rows to list.afterDatasourceResponse', async () => {
+    await aggregate(totals, 'bob');
+    expect(afterHookCalls).toEqual([{
+      query: expect.objectContaining({ aggregations: totals.aggregations }),
+      response: [{ orders: 1, revenue: 5, currency: 'USD' }],
+    }]);
+  });
+});