HarperFast / HarperFast/harper

REST: support ?max-age=<seconds> TTL override on @table resources (not just isCaching)

Open
#1,226 0 comments 0 reactions 1 assignee Claimed by @kriszyp View on GitHub
area:rest-api enhancement
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

## Summary

The `?max-age=` query parameter for overriding a record's TTL at write time is not implemented for regular `@table(expiration:)` resources. It only works for `isCaching` resources via the `Cache-Control: max-age` request header.

## Current behavior

PUT/POST to a regular `@table(expiration: N)` resource ignores any `?max-age=` query parameter. The record always expires at the table-level default.

## Desired behavior

A writer can override the TTL on a per-record basis:
```
PUT /ShortLived/item1?max-age=600 → record expires in 600s regardless of table default
```

This is analogous to HTTP cache semantics where the origin can set a per-response TTL.

## Motivation

Found while writing integration tests for fleet-informed test plan (#1191). Production clusters use this pattern:
- Walmart USGM redirect service uses `?max-age=` to set per-redirect expiry at write time (overriding the 1-year table default)

## Implementation notes

The hook point is in `server/REST.ts`: the `isCaching` branch already parses `cache-control: max-age` for caching resources. The `@table` resource path would need to read `req.query['max-age']` and apply it as the record's `expiresAt`.

The existing `expiration` table attribute and `?max-age` header form both ultimately set `expiresAt` on the record — this is about exposing that same mechanism via query parameter for any table type.

## Tracking

Placeholder test exists in `integrationTests/apiTests/ttl.test.ts` (test 3, marked TODO).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.