Upgrade / Upgrading to 0.14
Upgrade / upgrade-0-14
Upgrading to 0.14
No schema change. Request limits, key rotation, retention, more hooks and the events stream are all off until you set them.
On this page
From 0.13.x. See Limits, key rotation, retention and events. There is no schema change and nothing behaves differently until you set one of the new options.
1. Screens#
npx @mainsoft/agent-cms add --update # cms-keys, cms-messagesThe keys screen gains "Rotate", "Requests per minute" and "Allowed addresses".
2. Request limits are off until you set them#
createCms({
rateLimit: { perMinute: 600, anonymousPerMinute: 120 },
});perMinuteis for each API key; a key's ownrateLimitwins over it.anonymousPerMinuteis for each address that sends no key and has no session. Signed-in people are not counted.- Over the limit: 429
rate_limited,Retry-Afterin seconds. - Counting is per server process. With several servers, or on serverless, give a shared store:
rateLimit: {
perMinute: 600,
store: { hit: async (bucket, ttlMs) => { const n = await redis.incr(bucket); if (n === 1) await redis.pexpire(bucket, ttlMs); return n; } },
}The caller's address is read from X-Forwarded-For (first entry), then X-Real-IP. If your server is not behind a proxy that sets those, a client can send the header itself: pass createCmsHandler({ clientIp: (req) => … }).
3. Rotating a key#
POST /keys/:id/rotate with { "graceMinutes": 60 } returns a new secret. The old one works until the grace time ends. 0 cuts it off at once. A rotated key shows as "Replaced" in the list once its time is over.
4. Retention is off until you set it#
createCms({ retention: { auditDays: 365, hitsDays: 400, revokedKeysDays: 90 } });It runs with the cron call, at most once a day. Try it first: npx @mainsoft/agent-cms retention --dry-run (an admin key).
5. Types#
CreateCmsOptionsgainedrateLimitandretention;CmsHandlerOptionsgainedclientIp.CmsKeygainedrateLimit,allowedIps,revokedReason,rotatedTo. A key withrevokedAtin the future is a rotated key that still works: compare with the current time before calling it revoked.- A custom
CmsReponeedsprune(what, before, dryRun), andrevokeKeymust accept a time in the future.MemoryRepoandDrizzleRepodo both. - New hooks on a collection:
beforeValidate,afterPublish,afterDelete,afterRead. - New error codes:
rate_limited(429),forbidden_ip,forbidden_admin,invalid_ip_range,invalid_rate_limit. retention,_eventsandauthare reserved names: a collection cannot have those slugs.