diff --git a/modules/nats/cmd/nats-tools/removal.go b/modules/nats/cmd/nats-tools/removal.go index 2d4b804af..d6a9e0ae5 100644 --- a/modules/nats/cmd/nats-tools/removal.go +++ b/modules/nats/cmd/nats-tools/removal.go @@ -35,6 +35,7 @@ const ( consumerRemoved = "consumer-removed" bucketKeysRemoved = "bucket-keys-removed" streamRemoved = "stream-removed" + streamPurged = "stream-purged" // maxKeysShown bounds the keys an answer lists; the count is always whole. maxKeysShown = 200 ) @@ -332,7 +333,6 @@ func RemoveStream(ctx context.Context, bus Bus, said Said, a map[string]any) (an return out, nil } -// removalTools are the module's three tools that change the bus; every other tool here reads. // removalTools are the three removal tools. **They refuse an entry of the new form** (design 25 § 12.3; ADR 0595 §4 as // its insight of 2026-11-03 has it): the mesh deletes a module's kept data only through the bus module's drop and // recreate, so a stream, a bucket or a consumer of a stream the keeper made (its state asked, read through newForm) is @@ -360,6 +360,11 @@ func removalTools(bus Bus, said Said, newForm heldEntries) []stdio.Tool { Description: "Removes (deletes) one named JetStream stream whole, e.g. a stream the controller left: CONTROL, ASSIGNMENTS, one of its buckets as KV_ or a node's declaration files as OBJ_declaration-files- (novox/hq ADR 0590 §6; a bucket's whole removal is this tool's, never nats_bucket_remove's). Needs `why`, kept in the audit trail; reads the stream first and answers its messages, bytes and consumers; refuses a stream that still has a consumer; a stream already gone is answered as such and is no error, so asking again is safe. `dry_run` only reads. The bus refuses any stream the module's credential is not granted.", Input: map[string]any{"stream": str("the stream, e.g. ASSIGNMENTS"), "why": str("why it is removed, for the audit trail (required)"), "dry_run": map[string]any{"type": "boolean", "description": "read the stream, remove nothing"}}, Run: run(RemoveStream)}, + {Name: "nats_stream_purge", + Description: "Purges (removes) the messages of one named JetStream stream below a sequence, keeping that sequence and every later one: e.g. a build seat's work queue (SEAT_NODE_BUILD_GO) emptied of old asks nobody waits for, up to the first ask still wanted. Needs `why`, kept in the audit trail; reads the stream first and answers its first and last sequence and its messages before and after; the stream and its consumers stay; refuses a `below` past the stream's end (a whole purge is not this tool's). `dry_run` only reads. Read the sequences with nats_stream_messages. The bus refuses any stream the module's credential is not granted.", + Input: map[string]any{"stream": str("the stream, e.g. SEAT_NODE_BUILD_GO"), "below": num("the first sequence kept: every message below it is purged"), + "why": str("why they are purged, for the audit trail (required)"), "dry_run": map[string]any{"type": "boolean", "description": "read the stream, purge nothing"}}, + Run: run(PurgeStream)}, {Name: "nats_bucket_remove", Description: "Removes (purges) keys from a key-value bucket: one node's keys (`node`, the keys starting `.`) or the keys under a `prefix`, e.g. a full acts bucket of the node-engine. Needs `why`, kept in the audit trail; never the whole bucket. Counts the keys first and lists them (`dry_run` only counts; `expect` refuses when the count differs); removes only those keys, and their history. See the buckets and their keys with nats_buckets. The bus refuses any bucket the module's credential is not granted.", Input: map[string]any{"bucket": str("the bucket as nats_buckets lists it, e.g. mesh-host_acts"), "node": str("a node whose keys (`.`) go"), "prefix": str("key prefix instead of node"), @@ -388,3 +393,87 @@ func refuseNewForm(newForm heldEntries, stream string) error { } return nil } + +// StreamPurged is what nats_stream_purge answers and says. +type StreamPurged struct { + Stream string `json:"stream"` + Below uint64 `json:"below"` + Why string `json:"why"` + DryRun bool `json:"dry_run"` + First uint64 `json:"first_seq"` + Last uint64 `json:"last_seq"` + Before uint64 `json:"messages_before"` + After uint64 `json:"messages_after"` + Purged uint64 `json:"purged"` + Said string `json:"said"` + At time.Time `json:"at"` +} + +// PurgeStream removes the messages of one named stream below a sequence, keeping that sequence and every later one, +// after reading the stream, and says so: a work queue whose old asks nobody waits for any more is emptied up to the +// first ask still wanted (issue 1952's removal tools, one more of their kind). The stream and its consumers stay. +func PurgeStream(ctx context.Context, bus Bus, said Said, a map[string]any) (any, error) { + w, err := why(a) + if err != nil { + return nil, err + } + stream := arg(a, "stream") + if !name.MatchString(stream) { + return nil, errors.New("stream is required, one stream's name (letters, digits, - and _): nothing was purged") + } + below, ok := a["below"].(float64) + if !ok || below < 2 || below != float64(uint64(below)) { + return nil, errors.New("below is required, the first sequence kept (a whole number above 1): nothing was purged") + } + dry, _ := a["dry_run"].(bool) + js, closeBus, err := bus(ctx) + if err != nil { + return nil, err + } + defer closeBus() + out := StreamPurged{Stream: stream, Below: uint64(below), Why: w, DryRun: dry, At: time.Now().UTC()} + sctx, cancel := step(ctx) + s, err := js.Stream(sctx, stream) + cancel() + if err != nil { + return nil, unanswered(err, fmt.Sprintf("the stream %s could not be read, so nothing was purged", stream)) + } + sctx, cancel = step(ctx) + info, err := s.Info(sctx) + cancel() + if err != nil { + return nil, unanswered(err, fmt.Sprintf("the stream %s could not be read, so nothing was purged", stream)) + } + out.First, out.Last, out.Before = info.State.FirstSeq, info.State.LastSeq, info.State.Msgs + if out.Below > out.Last+1 { + return nil, fmt.Errorf("%s ends at sequence %d: below %d would purge it whole, which is not this tool's; nothing was purged", stream, out.Last, out.Below) + } + if dry { + out.Said = fmt.Sprintf("%s holds %d messages, sequences %d to %d; those below %d would be purged", stream, out.Before, out.First, out.Last, out.Below) + return out, nil + } + sctx, cancel = step(ctx) + err = s.Purge(sctx, jetstream.WithPurgeSequence(out.Below)) + cancel() + if err != nil { + return nil, unanswered(err, fmt.Sprintf("the messages of %s below %d were not purged", stream, out.Below)) + } + sctx, cancel = step(ctx) + info, err = s.Info(sctx) + cancel() + if err != nil { + return nil, unanswered(err, fmt.Sprintf("the purge of %s below %d was accepted but could not be confirmed", stream, out.Below)) + } + if info.State.FirstSeq < out.Below && info.State.Msgs > 0 { + return nil, fmt.Errorf("%s still starts at sequence %d after the purge below %d was accepted", stream, info.State.FirstSeq, out.Below) + } + out.After = info.State.Msgs + if out.Before > out.After { + out.Purged = out.Before - out.After + } + out.Said = fmt.Sprintf("%s: %d messages below sequence %d purged, %d kept", stream, out.Purged, out.Below, out.After) + if err := said(streamPurged, out); err != nil { + return nil, fmt.Errorf("the messages of %s below %d WERE purged (%s) but the audit event could not be said: %w", stream, out.Below, w, err) + } + return out, nil +} diff --git a/modules/nats/module.json b/modules/nats/module.json index ab20bcd8a..75e59564f 100644 --- a/modules/nats/module.json +++ b/modules/nats/module.json @@ -57,6 +57,7 @@ "consumer-removed", "bucket-keys-removed", "stream-removed", + "stream-purged", "bucket-expiry-set", "snapshot-restored" ], @@ -171,6 +172,7 @@ "nats_consumer_remove", "nats_bucket_remove", "nats_stream_remove", + "nats_stream_purge", "nats_bucket_expiry", "nats_history", "nats_create",