Request Cost accounting - adding a cost for various api request actions. by wezell · Pull Request #32890 · dotCMS/core

wezell · 2025-08-01T22:45:19Z

This PR Implements a request cost accounting system that tracks API usage and provides optional rate limiting using a leaky token bucket algorithm.

Key Features

Request Cost Tracking

Assigns cost values to expensive operations (ES queries, file operations, image processing, etc.)
Uses ByteBuddy AOP to intercept annotated methods via @RequestCost
Adds x-dotrequest-cost response header showing request cost
Periodic logging of request metrics (requests, total cost, avg cost per request)

Optional Rate Limiting

Leaky token bucket implementation (LeakyTokenBucketImpl)
Adds x-dotratelimit-toks-max response header showing how many tokens remain in bucket and the max bucket value.
Configurable via RATE_LIMIT_ENABLED, RATE_LIMIT_REFILL_PER_SECOND, RATE_LIMIT_MAX_BUCKET_SIZE
Disabled by default.
When enabled, it will subtract the cost of any request from the tokens in the bucket. The bucket will refill at the rate of RATE_LIMIT_REFILL_PER_SECOND. If the bucket is empty, the rate limiter will reject requests with a 429 or To Many Request error when tokens are exhausted.

Accounting Modes

If you are logged in, you can add a query parameter dotAccounting to any request to get an accounting of its cost, e.g.

https://local.dotcms.site:8443/?dotAccounting=LOG

NONE - No tracking
HEADER - Cost in response header (default)
LOG - Detailed logging per operation
HTML - Visual report for debugging (admin only)

Configuration with defaults

  REQUEST_COST_ACCOUNTING_ENABLED=true     # Enable/disable cost reporting
  REQUEST_COST_TIME_WINDOW_SECONDS=60      # Cost Logging interval
  RATE_LIMIT_ENABLED=false                 # Enable hard rate limiting
  RATE_LIMIT_REFILL_PER_SECOND=500         # Token refill rate
  RATE_LIMIT_MAX_BUCKET_SIZE=10000         # Max tokens
  RATE_LIMIT_ADD_HEADER_INFO=true          # Adds header which reports on number of tokens remaining

Tests

Added unit tests for RequestCostApi, RequestCostFilter, RequestCostRequestListener, LeakyTokenBucketImpl and RequestCostReport for validation.
Integration tests verify HTML report behavior and accounting stability across requests.

To Do

Create a new LeakyTokenBucketImpl that reads token and bucket information from reddit for use across load balanced systems.
Log expensive requests, e.g. log any request > 1000 tokens

ref: #32886

This PR fixes: #32886

…adding a cost for various api request actions. ref: #32886

Implementing request costing. - Adding annotation for @RequestCost(increment=2) - RequestCostAPI - Adding appropriate annotations - Adding cost reporting ref: #32890

Implementing request costing. - Adding Tests ref: #32890

Implementing request costing. fixing annotations ref: #32890

Implementing request costing. fixing reporting ref: #32890

Using an Enum to centralize pricing ref: #32890

Fixing Tests ref: #32890

…appens in real time, not after a request has finished. ref: #32886

ref: #32886

sfreudenthaler

my friend Claude and I agree that this is good to go 🥇 🤖

This PR fixes: #34300 ## Cleanup: Remove container variantId usage and use page-level variantId ### Problem The codebase was attempting to extract `variantId` from container objects via `container?.parentPermissionable?.variantId`, but this property no longer exists after [PR #32890](#32890). This resulted in `variantId` always being `undefined` when used in container operations. Additionally, containers don't actually have `variantId` - it's a **page-level concept**, not a container-level one. The `/api/v1/page/copyContent` endpoint expects the **page-level variantId** in the `DotTreeNode` payload, not a container's variantId. ### Changes 1. **Removed `variantId` from `getContainersData` function** (`libs/sdk/uve/src/lib/dom/dom.utils.ts`) - Removed the TODO comment and code attempting to extract `variantId` from `parentPermissionable.variantId` - This property no longer exists in the API response 2. **Removed `variantId` from `EditableContainerData` interface** (`libs/sdk/types/src/lib/editor/public.ts`) - Removed the optional `variantId?: string` property since containers don't have variantId 3. **Updated `getCurrentTreeNode` to use page-level variantId** (`libs/portlets/edit-ema/portlet/src/lib/store/features/editor/withEditor.ts`) - Changed from using `container.variantId` to `store.$variantId()` which provides the page-level variantId - This ensures the correct variantId is sent to the `/api/v1/page/copyContent` endpoint 4. **Made `ContainerPayload.variantId` optional** (`libs/portlets/edit-ema/portlet/src/lib/shared/models.ts`) - Changed from `variantId: string` to `variantId?: string` with documentation explaining containers don't have variantId 5. **Updated tests** (`libs/portlets/edit-ema/portlet/src/lib/store/features/editor/withEditor.spec.ts`) - Updated test expectations to verify page-level variantId is used - Added test cases to ensure container variantId is ignored ### Impact - ✅ **Fixes incorrect API calls**: The `/api/v1/page/copyContent` endpoint now receives the correct page-level variantId instead of `undefined` - ✅ **Removes dead code**: Eliminates code attempting to access a non-existent property - ✅ **Improves code clarity**: Makes it explicit that variantId is a page-level concept, not container-level - ✅ **No breaking changes**: `ContainerPayload.variantId` is now optional, maintaining backward compatibility ### Testing - Updated unit tests to verify `getCurrentTreeNode` uses page-level variantId from `store.$variantId()` - Added test cases to ensure container variantId is properly ignored - All existing tests pass ### Related - Related to issue: [Issue #34300](#34300) - Follows up on: [PR #32890](#32890) which removed `parentPermissionable` from container API responses

…ns. (#32890) This PR Implements a request cost accounting system that tracks API usage and provides optional rate limiting using a leaky token bucket algorithm. ## Key Features ### Request Cost Tracking - Assigns cost values to expensive operations (ES queries, file operations, image processing, etc.) - Uses ByteBuddy AOP to intercept annotated methods via @RequestCost - Adds `x-dotrequest-cost` response header showing request cost - Periodic logging of request metrics (requests, total cost, avg cost per request) ### Optional Rate Limiting - Leaky token bucket implementation (LeakyTokenBucketImpl) - Adds `x-dotratelimit-toks-max` response header showing how many tokens remain in bucket and the max bucket value. - Configurable via `RATE_LIMIT_ENABLED`, `RATE_LIMIT_REFILL_PER_SECOND`, `RATE_LIMIT_MAX_BUCKET_SIZE` - Disabled by default. - When enabled, it will subtract the cost of any request from the tokens in the bucket. The bucket will refill at the rate of `RATE_LIMIT_REFILL_PER_SECOND`. If the bucket is empty, the rate limiter will reject requests with a `429` or `To Many Request` error when tokens are exhausted. <img width="592" height="297" alt="Screenshot 2026-01-07 at 10 08 45 AM" src="https://github.com/user-attachments/assets/b96b9a75-abc0-478d-bac2-1715af0eb56c" /> ### Accounting Modes If you are logged in, you can add a query parameter `dotAccounting` to any request to get an accounting of its cost, e.g. ``` https://local.dotcms.site:8443/?dotAccounting=LOG ``` - NONE - No tracking - HEADER - Cost in response header (default) - LOG - Detailed logging per operation - HTML - Visual report for debugging (admin only) ### Configuration with defaults ``` REQUEST_COST_ACCOUNTING_ENABLED=true # Enable/disable cost reporting REQUEST_COST_TIME_WINDOW_SECONDS=60 # Cost Logging interval RATE_LIMIT_ENABLED=false # Enable hard rate limiting RATE_LIMIT_REFILL_PER_SECOND=500 # Token refill rate RATE_LIMIT_MAX_BUCKET_SIZE=10000 # Max tokens RATE_LIMIT_ADD_HEADER_INFO=true # Adds header which reports on number of tokens remaining ``` ### Tests - Added unit tests for RequestCostApi, RequestCostFilter, RequestCostRequestListener, LeakyTokenBucketImpl and RequestCostReport for validation. - Integration tests verify HTML report behavior and accounting stability across requests. ### To Do - Create a new LeakyTokenBucketImpl that reads token and bucket information from reddit for use across load balanced systems. - Log expensive requests, e.g. log any request > 1000 tokens ref: #32886

This PR fixes: #34300 ## Cleanup: Remove container variantId usage and use page-level variantId ### Problem The codebase was attempting to extract `variantId` from container objects via `container?.parentPermissionable?.variantId`, but this property no longer exists after [PR #32890](#32890). This resulted in `variantId` always being `undefined` when used in container operations. Additionally, containers don't actually have `variantId` - it's a **page-level concept**, not a container-level one. The `/api/v1/page/copyContent` endpoint expects the **page-level variantId** in the `DotTreeNode` payload, not a container's variantId. ### Changes 1. **Removed `variantId` from `getContainersData` function** (`libs/sdk/uve/src/lib/dom/dom.utils.ts`) - Removed the TODO comment and code attempting to extract `variantId` from `parentPermissionable.variantId` - This property no longer exists in the API response 2. **Removed `variantId` from `EditableContainerData` interface** (`libs/sdk/types/src/lib/editor/public.ts`) - Removed the optional `variantId?: string` property since containers don't have variantId 3. **Updated `getCurrentTreeNode` to use page-level variantId** (`libs/portlets/edit-ema/portlet/src/lib/store/features/editor/withEditor.ts`) - Changed from using `container.variantId` to `store.$variantId()` which provides the page-level variantId - This ensures the correct variantId is sent to the `/api/v1/page/copyContent` endpoint 4. **Made `ContainerPayload.variantId` optional** (`libs/portlets/edit-ema/portlet/src/lib/shared/models.ts`) - Changed from `variantId: string` to `variantId?: string` with documentation explaining containers don't have variantId 5. **Updated tests** (`libs/portlets/edit-ema/portlet/src/lib/store/features/editor/withEditor.spec.ts`) - Updated test expectations to verify page-level variantId is used - Added test cases to ensure container variantId is ignored ### Impact - ✅ **Fixes incorrect API calls**: The `/api/v1/page/copyContent` endpoint now receives the correct page-level variantId instead of `undefined` - ✅ **Removes dead code**: Eliminates code attempting to access a non-existent property - ✅ **Improves code clarity**: Makes it explicit that variantId is a page-level concept, not container-level - ✅ **No breaking changes**: `ContainerPayload.variantId` is now optional, maintaining backward compatibility ### Testing - Updated unit tests to verify `getCurrentTreeNode` uses page-level variantId from `store.$variantId()` - Added test cases to ensure container variantId is properly ignored - All existing tests pass ### Related - Related to issue: [Issue #34300](#34300) - Follows up on: [PR #32890](#32890) which removed `parentPermissionable` from container API responses

feat(api costing): this is a poc of how we could do api accounting - …

048ac7b

…adding a cost for various api request actions. ref: #32886

github-actions Bot mentioned this pull request Aug 1, 2025

per Request based accounting - calculate cost for each request #32886

Open

wezell marked this pull request as draft August 1, 2025 22:46

wezell added 3 commits August 1, 2025 18:47

Merge branch 'main' into issue-32886-request-cost

9438b3a

feat(api costing): this is a poc of how we could do api accounting - …

8264def

…adding a cost for various api request actions. ref: #32886

feat(api costing): this is a poc of how we could do api accounting - …

f5d596e

…adding a cost for various api request actions. ref: #32886

jdotcms reviewed Aug 11, 2025

View reviewed changes

Comment thread dotCMS/src/main/java/com/dotcms/content/elasticsearch/business/ESContentletAPIImpl.java Outdated

jdotcms reviewed Aug 11, 2025

View reviewed changes

Comment thread dotCMS/src/main/java/com/dotcms/cost/RequestCostApi.java Outdated

jdotcms approved these changes Aug 11, 2025

View reviewed changes

github-actions Bot added the stale label Sep 11, 2025

github-actions Bot closed this Sep 19, 2025

wezell reopened this Oct 7, 2025

Merge branch 'main' into issue-32886-request-cost

bce8b27

wezell changed the title ~~feat(api costing): this is a poc of how we could do api accounting - adding a cost for various api request actions.~~ feat(api costing): api accounting - adding a cost for various api request actions. Oct 7, 2025

github-actions Bot removed the stale label Oct 8, 2025

wezell added 10 commits October 13, 2025 14:12

feat(cost):

2ce603a

Implementing request costing. - Adding annotation for @RequestCost(increment=2) - RequestCostAPI - Adding appropriate annotations - Adding cost reporting ref: #32890

feat(cost):

acfaa80

Implementing request costing. - Adding Tests ref: #32890

feat(cost):

078472e

Implementing request costing. - Adding Tests ref: #32890

feat(cost):

4c171fa

Implementing request costing. fixing annotations ref: #32890

feat(cost):

20aa314

Implementing request costing. fixing reporting ref: #32890

feat(cost):

fa9391a

Using an Enum to centralize pricing ref: #32890

feat(cost):

9b94bb6

Using an Enum to centralize pricing ref: #32890

Merge branch 'main' into issue-32886-request-cost

caab4c7

Merge remote-tracking branch 'origin/main' into issue-32886-request-cost

809fcd6

feat(cost):

61118b5

Using an Enum to centralize pricing ref: #32890

dotCMS deleted a comment from github-actions Bot Oct 15, 2025

wezell added 3 commits October 15, 2025 14:22

Merge remote-tracking branch 'origin/main' into issue-32886-request-cost

049c210

feat(cost):

d817362

Fixing Tests ref: #32890

feat(cost):

2c1950d

Fixing Tests ref: #32890

wezell requested a review from dsilvam December 23, 2025 13:48

wezell added 16 commits December 23, 2025 10:07

Merge remote-tracking branch 'origin/main' into issue-32886-request-cost

2d74f63

Merge branch 'main' into issue-32886-request-cost

231eaa9

feat(cost): CDI LeakyTokenBucket for rate limiting. Also accounting h…

fda1b27

…appens in real time, not after a request has finished. ref: #32886

feat(cost): fixing postman tests

95e613f

ref: #32886

feat(cost): fixing postman tests

ee1fa28

ref: #32886

feat(cost): fixing Unit tests

29d425c

ref: #32886

Merge branch 'main' into issue-32886-request-cost

7746860

feat(cost): fixing Postman tests

bb7e408

ref: #32886

feat(cost): adding logging when rate limit is hit.

28c2b5e

ref: #32886

feat(cost): adding request totals

b63bd3a

ref: #32886

feat(cost): adding request totals

8d04507

ref: #32886

feat(cost): Logging

82c5136

ref: #32886

feat(cost): Logging

00d9d1d

ref: #32886

feat(cost): Logging

a438547

ref: #32886

feat(cost): Adding ability to configure Rate Limit at runtime

ab10d41

ref: #32886

feat(cost): Adding ability to configure Rate Limit at runtime

c1e3387

ref: #32886

spbolton approved these changes Jan 7, 2026

View reviewed changes

sfreudenthaler approved these changes Jan 7, 2026

View reviewed changes

Comment thread dotCMS/src/main/java/com/dotcms/content/elasticsearch/business/ESContentletAPIImpl.java

wezell added this pull request to the merge queue Jan 7, 2026

Merged via the queue into main with commit f2992b2 Jan 7, 2026
42 checks passed

wezell deleted the issue-32886-request-cost branch January 7, 2026 17:36

This was referenced Jan 26, 2026

chore(UVE): Remove unsued variantId in ContainerPayload #34404

Closed

[SPIKE] SDK: Re-visit Dependency on parentPermissionable for Container variantId #34300

Closed

chore(UVE): Remove unsued variantId in ContainerPayload #34410

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Request Cost accounting - adding a cost for various api request actions.#32890

Request Cost accounting - adding a cost for various api request actions.#32890
wezell merged 70 commits intomainfrom
issue-32886-request-cost

wezell commented Aug 1, 2025 •

edited by github-actions Bot

Loading

Uh oh!

Uh oh!

Uh oh!

sfreudenthaler left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

wezell commented Aug 1, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Features

Request Cost Tracking

Optional Rate Limiting

Accounting Modes

Configuration with defaults

Tests

To Do

Uh oh!

Uh oh!

Uh oh!

sfreudenthaler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

wezell commented Aug 1, 2025 •

edited by github-actions Bot

Loading