From 32e27d0864e8a455f9e393067697c4cdbb2f494c Mon Sep 17 00:00:00 2001 From: razbroc Date: Mon, 10 Aug 2026 17:31:54 +0300 Subject: [PATCH] feat: split cache deletion into swap and update job types Replaces the single Delete_Cache job type with Swap_Delete_Cache and Update_Delete_Cache. Cache invalidation after a layer swap and after an in-place update are different operations with different task parameters: a swap invalidates the whole key prefix, an update invalidates specific tile ranges. Workers resolve strategies by the (jobType, taskType) pair, so a single Delete_Cache job type collapsed both cases onto one token and forced the strategy to discriminate on the parameter shape at runtime. Two job types give two tokens and let each resolve to its own strategy. The cache-deletion task type is unchanged and used by both. Adds CONTEXT.md, a glossary for the deletion and storage vocabulary. --- CONTEXT.md | 55 +++++++++++++++++++++++++++++ src/constants/deletion/constants.ts | 19 +++++++++- 2 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 CONTEXT.md diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..3e11f7f --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,55 @@ +# Context + +Glossary for the Raster domain as this package models it. Terms only — no implementation +detail, no specification. If a term here disagrees with the code, one of them is wrong. + +## Deletion + +**Layer deletion** — Removing a layer from the system entirely: its catalog record, its +serving configuration, its polygon parts, and its stored resources. Terminal; the layer +ceases to exist. Job type `Delete_Layer`. + +**Cache deletion** — Invalidating entries in the Redis tile cache so that stale tiles stop +being served. The layer itself survives. Distinct from layer deletion in both intent and +lifetime: cache deletion is routine maintenance that follows a change to a live layer, not +the retirement of one. + +**Swap cache invalidation** — Cache deletion following a layer _swap_, where the layer's +tiles were replaced wholesale. Every cached entry for the layer is stale, so the whole key +prefix is removed. Job type `Swap_Delete_Cache`. + +**Update cache invalidation** — Cache deletion following an _in-place update_, where only +part of the layer changed. Only the affected tiles are stale, so invalidation is scoped to +a set of tile ranges. Job type `Update_Delete_Cache`. + +**Artifacts deletion** — Removing a layer's non-tile stored resources (GPKG files, +metadata files, and similar) from their storage provider. Job type `Delete_Layer`, task +type `artifacts-deletion`. + +**Tiles deletion** — Removing tile _files_ from a path-based store (S3 or FS), addressed by +a base path, tile ranges, and a file extension. Not to be confused with cache deletion, +which removes cache _entries_ from a key-value store and has no paths or file extensions. + +## Storage + +**Source type** — Where raster data originates: `S3`, `GPKG`, or `FS`. + +**Storage provider** — Where a deletion operation acts: `S3`, `FS`, or `REDIS`. Deliberately +a separate term from source type: Redis is a deletion target but never a data source, and +GPKG is a data source but never a deletion target. The two sets overlap without being equal. + +**Prefix** — The locator for a set of entries in a key-value store, as a path is the locator +for a file. For the Redis tile cache, a prefix identifies every cached tile belonging to one +layer in one grid. + +## Jobs and tasks + +**Job type** — What work was requested and why, chosen when the job is created. It reflects +the upstream event (a swap happened, an update happened, a layer was retired). + +**Task type** — What kind of work a single unit performs. + +A task's parameter shape is determined by the **pair** of job type and task type, not by the +task type alone. The same task type carries different parameters under different job types — +this is deliberate, and it is why task types are not sufficient on their own to identify a +unit of work. diff --git a/src/constants/deletion/constants.ts b/src/constants/deletion/constants.ts index 8b0a81e..f5acc9f 100644 --- a/src/constants/deletion/constants.ts +++ b/src/constants/deletion/constants.ts @@ -1,7 +1,18 @@ /* eslint-disable @typescript-eslint/naming-convention */ export const DeletionJobTypes = { Delete_Layer: 'Delete_Layer', - Delete_Cache: 'Delete_Cache', + /** + * Cache invalidation following a layer swap: the previous cache is stale in its entirety. + * Paired with {@link DeletionTaskTypes.CacheDeletion}, whose task parameters are + * `redisDeleteStoredResourcesParamsSchema` — the key `prefix` alone locates everything to remove. + */ + Swap_Delete_Cache: 'Swap_Delete_Cache', + /** + * Cache invalidation following an in-place layer update: only the updated tiles are stale. + * Paired with {@link DeletionTaskTypes.CacheDeletion}, whose task parameters are + * `redisTilesDeletionParamsSchema` — the key `prefix` plus the `ranges` to invalidate. + */ + Update_Delete_Cache: 'Update_Delete_Cache', } as const; export type DeletionJobTypes = (typeof DeletionJobTypes)[keyof typeof DeletionJobTypes]; @@ -10,7 +21,13 @@ export const DeletionTaskTypes = { Delete: 'delete', LayerTilesDeletion: 'tiles-deletion', ArtifactsDeletion: 'artifacts-deletion', + /** + * Removal of entries from the Redis tile cache. The parameter shape is decided by the job type + * this task is paired with — see {@link DeletionJobTypes.Swap_Delete_Cache} and + * {@link DeletionJobTypes.Update_Delete_Cache}. + */ CacheDeletion: 'cache-deletion', } as const; export type DeletionTaskTypes = (typeof DeletionTaskTypes)[keyof typeof DeletionTaskTypes]; +/* eslint-enable @typescript-eslint/naming-convention */