nats: a tool purges a stream's messages below a sequence #695
@@ -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_<bucket> or a node's declaration files as OBJ_declaration-files-<node> (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 `<node>.`) 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 (`<node>.`) 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
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user