coracle-rust/book/research/expiring-events.md

# Research: Expiring Events

## Topic Summary

NIP-40 defines an optional `expiration` tag of the form
`["expiration", "<unix_timestamp_seconds>"]`. When present, it marks the
event as no longer valid after the given time. Relays SHOULD stop
serving expired events and MAY drop them from storage. Clients SHOULD
not display expired events. Expiration is a hint, not a cryptographic
guarantee — anyone who already has a copy can keep it.

This chapter should cover:
- Reading the `expiration` tag from an event's tags
- A predicate `is_expired` (and a testable `is_expired_at(now)` variant)
- Constructing an expiration tag
- Attaching free-function accessors to `HashedEvent` and `Event`
- Handling missing and malformed tags (treated as never-expires)

Mining, storage filtering, and relay-side enforcement are out of scope —
the chapter stays at the tag-parsing layer.

## Philosophy

From `ref/building-nostr`:

- The `expiration` tag is a **behavior tag** — orthogonal to kind,
  applicable to any event. It requests special handling by relays
  rather than encoding meaning in the payload.
- Expiration is a *superset* of ephemeral-kind (2XXXX) functionality.
  Putting retention policy in a tag frees it from the kind range.
- Expiration, like deletion (kind 5), is a **request, not a guarantee**:
  "once it's published, there's no way to un-sign or un-publish".
  Clients and relays cooperate voluntarily.
- Different content has different natural lifespans. Expiration is a
  design choice reflecting use case — chat messages can expire; wiki
  entries shouldn't.

The framing matters for the chapter: we are not building a deletion
mechanism. We are parsing an opt-in hint that downstream layers
(storage, UI, relay policy) may act on.

## Reference Implementation Analysis

### applesauce

- `getExpirationTimestamp(event)` reads the first `expiration` tag and
  parses its value as a number; caches the parsed value via a Symbol.
- `isExpired(event)` compares the cached timestamp to `unixNow()`
  (`Math.round(Date.now() / 1000)`). Missing tag → returns `false`.
- `setExpirationTimestamp(n)` is an event-builder operation that
  replaces any existing expiration tag with `["expiration", n.toString()]`.
- `ExpirationManager` is an injectable storage-layer component that
  tracks non-expired events and emits an `expired$` observable; an
  `EventStore` filters expired events out of queries unless
  `keepExpired: true`.
- Time is wall-clock only (`Date.now()`).

### ndk

- Minimal. Expiration is handled at the model level (e.g., a
  `P2POrderEvent` class has `expiration` getter/setter); no
  framework-wide `isExpired()` method.
- No storage-layer filtering of expired events.

### nostr-gadgets

- Nothing. Zero references to `expiration` or NIP-40.

### nostrlib (Go)

- `nip40.GetExpiration(tags) Timestamp` returns -1 on missing/malformed
  tag. Plain int64 parse.
- `khatru/expiration.go` is a separate opt-in relay-side manager:
  min-heap of expiring events, periodic sweep (default 1 hour), deletes
  on expiration. Not used at query time — strictly a background cleaner.
- Uses `nostr.Now()` = `time.Now().Unix()`; no injection.

### nostr-tools

- `getExpiration(event)` → `Date` object (from unix seconds × 1000).
- `isEventExpired(event)` compares via `Date.now()`; missing tag → false.
- Bonus: `waitForExpire(event)` / `onExpire(event, cb)` schedule a
  `setTimeout` to fire when the event expires — async sugar, not
  essential to the core API.
- No tag constructor.

### rust-nostr

The most structured implementation:

- Tag modeled as `TagStandard::Expiration(Timestamp)` variant and
  `TagKind::Expiration` kind.
- Constructor: `Tag::expiration(timestamp: Timestamp) -> Tag`.
- Query: `Tags::expiration() -> Option<&Timestamp>`.
- Predicates on `Event`:
  - `is_expired_at(&self, now: &Timestamp) -> bool` — compares strictly
    with `<` (expiration equal to now is not yet expired).
  - `is_expired(&self) -> bool` (std only) — delegates to `now()`.
- `Timestamp` is a `u64` newtype in seconds. `Timestamp::now()` uses
  `SystemTime` with an unwrap-to-default fallback; no clock trait.
- Storage feature flag `event_expiration: bool` in the database trait;
  currently all backends set it to `false`, so filtering is
  application-level.

### welshman

- `Repository` maintains a separate `expired: Map<eventId, timestamp>`
  populated at insert time (parses `expiration` tag, skips NaN).
- `isExpired(event)` looks up in the map; strict `<` comparison.
- No builder for the tag; no automatic filtering in query paths.

## Common Patterns

- **Graceful absence.** Every implementation treats a missing
  expiration tag as "never expires". None returns an error on absent
  tags; most surface `Option` / `null` / a sentinel.
- **Graceful malformed.** Most implementations silently ignore tags
  whose value doesn't parse. None treats a malformed tag as expired.
- **Strict `<` comparison.** rust-nostr, welshman, and applesauce all
  use strict-less-than: an event whose expiration equals `now` is still
  valid. This is the natural reading of "expires at time T" (the event
  is invalid *after* T).
- **Wall-clock time.** No implementation injects a clock. Time comes
  from `SystemTime::now()` / `Date.now()` / `time.Now()`. Testable
  variants (passing `now` explicitly) are common.
- **Separation of parse from enforcement.** Parsing the tag is cheap
  and always available. Doing something about it (removing expired
  events from storage, hiding them in UI, sweeping a relay database)
  is a separate concern layered on top.
- **Minimal tag constructor.** Rust-nostr has one; most TS libraries
  expect the caller to build the tag by hand. Adding one is trivial
  and makes call sites readable.

## Considerations for Our Implementation

**Scope.** This crate is `coracle-lib`, which owns nostr types and
stateless utilities. The chapter stays at that layer: tag accessor,
predicate, tag constructor. Storage sweeping and UI hiding belong in
downstream crates (`coracle-storage`, future application code).

**API shape, closely tracking rust-nostr but flatter.** The library has
deliberately avoided a `TagStandard` enum in earlier chapters — `Tag`
is a thin `Vec<String>` wrapper with accessor methods. Following that
style:

- `get_expiration(tags: &Tags) -> Option<u64>` — free function.
- `is_expired_at(tags: &Tags, now: u64) -> bool`.
- `is_expired(tags: &Tags) -> bool` — uses `SystemTime::now()`.
- Methods `get_expiration / is_expired / is_expired_at` on both
  `HashedEvent` and `Event`, delegating to the free functions.
- A tag constructor. Two plausible shapes:
  - `Tag::expiration(ts: u64) -> Tag` — parallels `Tag::new` but
    specialized.
  - Just document that callers can write `Tag::new("expiration",
    [ts.to_string()])`.
  The existing `pow.rs` module builds the nonce tag inline via
  `Tag::new`, so there is a precedent for the inline form. But an
  expiration-specific constructor is small and keeps call sites more
  readable, and there's nothing nonstandard to hide. Lean toward
  providing it.

**Type for timestamps.** The rest of the library uses plain `u64` for
`created_at`. Consistency argues for `u64` here too; no new
`Timestamp` newtype.

**Comparison semantics.** Use strict `<`. Document it in the rustdoc.

**Graceful parsing.** Missing tag or unparseable value → `None` /
`false`. No errors surfaced to callers.

**Time source.** Use `SystemTime::now().duration_since(UNIX_EPOCH)`
directly in `is_expired`. Keep `is_expired_at` available as the
testable primitive. No clock trait — it would cost more than it buys
in a library this size.

**Dependencies.** None beyond what's already pulled in (`std::time`).

**Narrative.** The chapter should build on the proof-of-work chapter's
structure — free functions plus methods on event types — and lean on
the philosophy framing: expiration is a **behavior tag**, a request,
not a cryptographic property of the event. That framing prepares the
reader for later chapters where storage and relay layers act on it.