Let a bundle write a key with its own time to live and hear its expiry, so pulses, settles and bounds expire on the bus through the runtime (issue 1952)

go/state.go

@@ -20,7 +20,18 @@ type StateEntry struct {
 	Revision uint64          `json:"revision"`
 }
 
-// StateChange is one change a watch hands over: a key put or deleted.
+// The operations a watch hands over (StateChange.Op).
+const (
+	// OpPut is a key written.
+	OpPut = "put"
+	// OpDelete is a key deleted or purged.
+	OpDelete = "delete"
+	// OpExpire is a key whose own time to live ended (CreateTTL, PutTTL): the runtime says the bus's marker of it as
+	// "expire", so a watcher tells an expiry, which is the event a pulse or a bound waits for, from a delete.
+	OpExpire = "expire"
+)
+
+// StateChange is one change a watch hands over: a key put (OpPut), deleted (OpDelete) or expired (OpExpire).
 type StateChange struct {
 	State    string          `json:"state"`
 	Key      string          `json:"key"`
@@ -98,6 +109,27 @@ func (s KeptState) Put(key string, value any) (uint64, error) {
 	return put.Revision, json.Unmarshal(raw, &put)
 }
 
+// PutTTL writes a key whole with its own time to live — the owner's instances only — and returns the revision written:
+// the bus removes it when ttl passes and a watch hands that over as OpExpire. The state is declared `key-ttl`.
+func (s KeptState) PutTTL(key string, value any, ttl time.Duration) (uint64, error) {
+	raw, err := s.ask("put", map[string]any{"key": key, "value": value, "ttl_seconds": ttlSeconds(ttl)})
+	if err != nil {
+		return 0, err
+	}
+	var put struct {
+		Revision uint64 `json:"revision"`
+	}
+	return put.Revision, json.Unmarshal(raw, &put)
+}
+
+// ttlSeconds is a time to live as the runtime takes it, whole seconds, at least one.
+func ttlSeconds(ttl time.Duration) int64 {
+	if s := int64(ttl / time.Second); s > 1 {
+		return s
+	}
+	return 1
+}
+
 // Delete removes a key — the owner's instances only. A key that was not there is not an error.
 func (s KeptState) Delete(key string) error {
 	_, err := s.ask("delete", map[string]any{"key": key})