## Summary When usage tracking is on, a user who can use a chatbot or another push consumer can make usage records grow with no limit. AI requests of that consumer then become slow for all users, and they can fail on every request. Usage tracking is off by default. No stable release exists yet, so this bug with a security impact is handled in public, as in #3586615+s. ### The code - `AiContextUsage::addRoute()` (`src/Entity/AiContextUsage.php`, lines 278-285) adds each new path to a JSON list in the `routes` field. The field is `string_long` (line 99). There is no limit on the number of paths or on their length. - There is one usage record for each context item, consumer and entity. A record with no entity is shared by all users of a consumer. - The path comes from `AiContextRequestInfoResolver::getPath()`. On a chatbot request, the client can supply the path: a POST `path` value, a JSON `path` value, or a same-host Referer on an XHR or JSON request (`src/Service/AiContextRequestInfoResolver.php`, lines 544-566). `normalizeSuppliedPath()` (lines 673-712) removes the query string and the fragment, but it accepts a path of any length. - On each push, `AiContextUsageTracker::recordUsage()` loads the records of all delivered items in one `loadMultiple()` call (`src/Service/AiContextUsageTracker.php`, line 125). Then it decodes, encodes, and saves the full list of each record. - Cron deletes records by their `changed` time (`usage_max_age`, default 90 days). Since #3586678+s (!374), each use sets `changed` (lines 145, 167, 262, 299, and 316). So a record that is in use never expires by age. The `usage_max_records` limit also deletes the records with the oldest `changed` time first. ### Security impact - **Who:** a user who can send requests to a push consumer that delivers at least one context item, for example an agent chatbot. The user must have **Use Published AI Context in AI Features**. This permission is not restricted. Anonymous users can do this only on a site that gives this permission to the Anonymous role, for example for a public chatbot. `docs/developers/consumer_api.md` documents this setup. - **What they get:** no data. Each request can add one path of any length, up to the request body limit of the server. - **Result:** - AI requests of that consumer become slower for all users, because each push loads and saves the full lists. - When a save fails, the record stays as it is. It does not get smaller. When the saved value is larger than the MySQL or MariaDB `max_allowed_packet` limit, the database server also closes the connection. Later queries in the same request then fail. So the AI request can fail, although the module catches and logs the first error. - A PHP memory-limit error is a fatal error, not a `Throwable`. The `catch (\Throwable)` blocks in `AiContextBuildSystemPromptSubscriber::recordUsage()` (lines 218-246) and in `AiContextPreGenerateResponseSubscriber` (lines 298-318) cannot catch it. So the consumer can fail on every request until an administrator deletes the usage records or turns off usage tracking. - `AiContextAgentToolSubscriber::onToolFinished()` calls `recordToolUsed()` and `attachEntity()` with no try/catch (lines 133 and 140). `attachEntity()` runs on agent runs where a tool creates or edits an entity. An exception from these calls, for example a failed save, is not caught, so the agent run fails. - `AiContextAgentFinishedSubscriber::onAgentFinished()` calls `flushToolsUsed()` with no try/catch (line 49). Each time an agent run used a tool, it loads and saves all records of the run, with their full path lists. An exception there also makes the agent run fail. - When large records expire (`usage_max_age`) or the record count goes over `usage_max_records`, cron loads up to 200 of them at a time to delete them. Very large records can then make cron slow or stop it. This can also happen after usage tracking is turned off. - The page that clears usage records loads up to 200 records at a time. The usage listing loads 50 records for each page by default. Very large records can make these pages fail too. - **Not affected:** the usage pages escape the paths, so there is no stored XSS. Pull calls (function calls) do not create usage records. - **Versions:** 1.0.0-beta5, 1.0.0-rc1, and `1.0.x` at `65f20b72`. ## Steps to reproduce 1. Turn on usage tracking at `/admin/config/ai/context/settings/usage`. 2. Create a published context item that a chatbot consumer delivers on each request, for example a Global item. 3. Give a test role "Use Published AI Context in AI Features" and access to the chatbot. Log in as a user with that role. 4. Send chatbot requests with a JSON body that has a `path` value. Use a different path in each request, and make each path very long, for example `/` and 100,000 characters. 5. Open the usage record of the item at `/admin/config/ai/context/usage`. Expected result: the record keeps a short list of recent paths, and each path has a length limit. Actual result: the record keeps every path in full. The `routes` value grows with each request. Confirmed on `1.0.x` at `65f20b72`: `addRoute()` and `normalizeSuppliedPath()` still have no limits, and the two agent subscribers still have no try/catch around the usage tracker calls. The new tests for this fix fail on the `1.0.x` code at `9932f4ab`: 25 different paths give 25 stored paths, a path of 301 characters is stored in full, and a JSON `path` value of 2,049 characters is used as the path hint. ## Proposed resolution 1. Add `AiContextUsage::setRoutes()`. It keeps only the last 20 paths (`MAX_ROUTES`). It cuts each path to 255 characters (`MAX_ROUTE_LENGTH`) and adds "…" at the end. It ignores empty values and values that are not strings. A repeated path moves to the end. `addRoute()` uses `setRoutes()`, so all code that writes paths through the entity gets the limits. 2. In `AiContextRequestInfoResolver`, ignore a supplied path hint that is longer than 2,048 characters (`MAX_PATH_LENGTH`). The query string and the fragment are removed before the check, as now. `getPath()` then uses the next source. At the end, it uses the request path. 3. In `AiContextUsageTracker::attachEntity()`, when an older record is merged into the record of the run, put the old paths first. Then the limit removes the oldest paths, not the paths of the run. When `attachEntity()` creates a new record for another entity, the new record gets its first path through `addRoute()`, so the limits apply there too. 4. Count characters, not bytes (`mb_strlen()` and `Unicode::truncate()`). 5. Store the path, not the route name. On a chatbot request, the route is the API endpoint, and the path is the page of the user. 6. No post-update. A record that was saved before the fix is cut the next time a path is added to it. A record that is too large to load is not cut. Clear it. Unused records expire through the retention setting. 7. Catch usage tracking errors on the agent paths, as the push subscribers do: - In `AiContextAgentToolSubscriber::onToolFinished()`, put the `recordToolUsed()` call, the `extractEntityInfo()` call and the `attachEntity()` call in one `try` block. - In `AiContextAgentFinishedSubscriber::onAgentFinished()`, put the `flushToolsUsed()` call in a `try` block. - Catch `\Throwable` and log an error in the same format as `AiContextPreGenerateResponseSubscriber`, for example `'AiContextAgentToolSubscriber: Failed to record usage for agent run @runner, the agent run continues: @message'`, with the runner ID as `@runner` and `$e->getMessage()` as `@message`. `AiContextAgentFinishedSubscriber` logs the same message with its own class name. - `AiContextAgentFinishedSubscriber` has no logger. Add `@logger.channel.ai_context` to its service in `ai_context.services.yml`. - Then a usage tracking error is logged, and the agent run continues. - A PHP memory-limit error is fatal and is not a `Throwable`, so this try/catch cannot catch it. That is why the limits in items 1-3 are the main fix. The try/catch is a second safeguard for other errors, for example a failed save. 8. Update the docs: - `docs/features/usage_tracking.md`: the path limits. A record that was saved before the fix is cut the next time a path is added to it. A usage tracking error is logged, and the AI request or agent run continues. The steps to recover when large usage records make a consumer fail. - `docs/features/context_delivery.md`: a supplied path that is longer than 2,048 characters, without the query string, is ignored. - `docs/developers/services.md`: a supplied path that is longer than 2,048 characters (without the query string) is ignored. The limit counts characters, not bytes. `setPath()` returns FALSE for this path. Also the limits of a usage record, `setRoutes()`, and the merge order in `attachEntity()`. - `docs/developers/events.md`: both agent subscribers catch and log usage tracking errors. The tool subscriber also catches an error when it reads the tool output. The log message names the runner ID. With these limits, a record that is saved after the fix stays small: at most 20 paths of at most 255 characters. So these records can no longer cause the memory error, on the push paths or on the agent paths. A record that is already too large to load must be cleared (see item 6). Out of scope: - The request path itself (`getPathInfo()`) has no limit. The web server limits it, and it is not a client hint. - `tools_used` has no limit. The tool IDs come from the server, not from the client. - A path that is not valid UTF-8 can make `json_encode()` fail. This is not new. - The number of usage records. On an agent chatbot request, a client can send a different `entity_type`/`entity_id` in the request body each time. `getEntity()` does not check that the entity exists or that the user can view it. On the generic path, the entity comes from the caller's `entity_context` metadata. Each new value adds one small record. This costs one AI request for each record, and cron removes records over `usage_max_records` (default 10,000). ## Remaining tasks * [x] Fix: limits in `AiContextUsage` and `AiContextRequestInfoResolver`, and the merge order and the first path of a new record in `AiContextUsageTracker::attachEntity()` (done in a local branch on `1.0.x` at `65f20b72`, not pushed yet). * [x] Rebase on `1.0.x` (`65f20b72`). Resolve the conflict in `AiContextUsageTracker::attachEntity()` and keep both `setChangedTime()` and `addRoute()`. Remove the second `loadOnlyUsage()` method in `AiContextUsageTrackerTest`, and use the existing `createUsageContextItem()` helper. * [x] Add the try/catch in `AiContextAgentToolSubscriber::onToolFinished()` and `AiContextAgentFinishedSubscriber::onAgentFinished()`, and the logger argument in `ai_context.services.yml`. * [x] Kernel tests in `AiContextUsageTrackerTest`: * `testRoutesKeepRecentRoutesAndShortenLongRoutes()`: 25 paths give the last 20 paths, a repeated path moves to the end, and a path of 301 characters is cut to 255 characters with "…". * `testMergedRecordKeepsRoutesOfCurrentRun()`: the merge in `attachEntity()` removes the oldest paths, not the paths of the run. * `testAddRouteTrimsStoredList()`: `addRoute()` cuts a stored list with more than 20 paths, and ignores empty values and values that are not strings. * `testNewEntityRecordShortensLongRoute()`: a new record for a second entity gets a cut first path. * [x] Unit test `AiContextRequestInfoResolverTest::testGetPathIgnoresTooLongHint()`: a JSON `path` value of 2,049 characters is ignored, a long query string is removed before the check, a path of 2,048 characters is accepted (also with multibyte characters), and `setPath()` returns FALSE for a path of 2,049 characters. * [x] Kernel tests in `AiContextAgentToolSubscriberTest`, one for each subscriber: `testToolFinishedEventLogsUsageTrackerError()` and `testAgentFinishedEventLogsUsageTrackerError()`. The usage tracker throws an exception, the event dispatch does not fail, and one error is logged with the runner ID. * [x] Run the new and related kernel tests again on the branch head. These kernel tests pass: `AiContextAgentToolSubscriberTest`, `AiContextUsageTrackerTest`, `AiContextPreGenerateResponseSubscriberTest` and `AiContextUsagePruningTest`. * [ ] Run the unit tests `AiContextRequestInfoResolverTest` and `AiContextUsageTrackerTest` again on the branch head. They passed in an earlier local run, but the branch head adds the multibyte case to `testGetPathIgnoresTooLongHint()`. * [x] Update `usage_tracking.md` and `context_delivery.md`. * [x] Update `docs/developers/services.md`: a supplied path that is longer than 2,048 characters is ignored, and `setPath()` returns FALSE for it. Also the limits of a usage record. * [x] Update `docs/developers/events.md`: both agent subscribers catch and log usage tracking errors, also an error when the tool subscriber reads the tool output. * [ ] Push the branch to the issue fork and open the MR on `1.0.x`. Check that the pipeline passes, with the functional tests. * [ ] Manual check: the usage record page with 20 paths and a cut path. * [ ] Review and RTBC. ## User interface changes The usage record page (`/admin/config/ai/context/usage/{id}`) shows at most the last 20 paths, oldest first. A path that is longer than 255 characters ends with "…". The usage listing (`/admin/config/ai/context/usage`) does not show paths. Its Route filter searches only the stored paths. So it cannot find a record by an older path, or by the part of a long path that was cut. ## API changes All changed classes are `@internal`. - New `AiContextUsage::setRoutes(array $routes)`, which applies the limits. - New constants: `AiContextUsage::MAX_ROUTES` (20), `AiContextUsage::MAX_ROUTE_LENGTH` (255), and `AiContextRequestInfoResolver::MAX_PATH_LENGTH` (2048). - `AiContextUsage::addRoute()` moves a repeated path to the end. Before, the path kept its first position. - `AiContextRequestInfoResolver::setPath()` returns FALSE for a path that is longer than 2,048 characters. - `AiContextAgentFinishedSubscriber::__construct()` has a new second argument, `LoggerInterface $logger`. The service in `ai_context.services.yml` passes `@logger.channel.ai_context`. - `AiContextAgentToolSubscriber::onToolFinished()` and `AiContextAgentFinishedSubscriber::onAgentFinished()` no longer let an exception from the usage tracker go to the agent run. They log it. - `AiContextAgentToolSubscriber::onToolFinished()` also catches an error when it reads the tool output (`extractEntityInfo()`). This error is logged as "Failed to record usage", also when usage tracking is off. Before, this error went to the agent run. ## Data model changes None. The `routes` value stays a JSON list in a `string_long` field. There is no update hook. ## Release note On sites with usage tracking on, a user with "Use Published AI Context in AI Features" who could use a chatbot could make usage records very large, so AI requests became slow or failed. Each usage record now keeps only the last 20 request paths, each 255 characters or less, and a path hint that is longer than 2,048 characters is ignored. A record that was saved before this update is cut the next time a path is added to it. An error in usage tracking during an agent run is now logged, and the agent run continues. If a consumer already fails because of large usage records, first turn off usage tracking at `/admin/config/ai/context/settings/usage`. Then clear the records at `/admin/config/ai/context/settings/usage/clear`. If the clear page also fails, empty the `ai_context_usage` table (for example, `drush sql:query "TRUNCATE TABLE ai_context_usage"`) and rebuild the caches. > [!note] > Check the one that best describes your usage, or leave all unchecked if AI was not significantly used. > > * [ ] AI **Assisted Issue** \ > _Mainly written by a human; AI used for partial generation under full human supervision._ > > * [x] AI **Generated Issue** \ > _Mainly generated by AI, reviewed and approved by a human before this issue was created._