Skip to content

Extract LogEntry/PendingLogEntry traits into a new tlog_entry crate#234

Draft
lukevalenta wants to merge 1 commit intolvalenta/tlog-checkpoint-cratefrom
lvalenta/tlog-entry-crate
Draft

Extract LogEntry/PendingLogEntry traits into a new tlog_entry crate#234
lukevalenta wants to merge 1 commit intolvalenta/tlog-checkpoint-cratefrom
lvalenta/tlog-entry-crate

Conversation

@lukevalenta
Copy link
Copy Markdown
Contributor

Third slice of #230. Move LogEntry/PendingLogEntry traits + helpers (and the c2sp.org/tlog-tiles default entry-bundle implementation) out of tlog_tiles into a new internal tlog_entry crate. After this, each spec crate matches its C2SP slug exactly.

Stacked on PR #233 (slice 2: tlog_checkpoint). Diff against #233 is the new content here; once #231/#233 land this PR's base will be retargeted to main.

Why a new crate (and not generic_log_worker)

The natural framing of #230's slice 3 was "move worker abstractions to generic_log_worker". On closer reading, the situation is more nuanced: the traits are a worker ↔ spec interface, with multiple consumers on each side:

  • Implementors (spec-level): tlog_tiles (the default tlog-tiles entry-bundle), static_ct_api, bootstrap_mtc_api, soon ietf_mtc_api.
  • Consumer (worker-side): generic_log_worker.

generic_log_worker already depends on static_ct_api / bootstrap_mtc_api, so moving the trait definitions there would create a cycle. Putting them in any single spec crate forces every other spec crate to depend on it. A small interface crate (tlog_entry, publish = false) breaks the tangle cleanly.

What moves to tlog_entry

Symbol Old home Notes
PendingLogEntry, LogEntry traits tlog_tiles::entries The worker / spec interface.
PendingLogEntryBlob tlog_tiles::entries DO storage shape.
LookupKey, LOOKUP_KEY_LEN tlog_tiles::entries Cache/dedup key.
TileIterator tlog_tiles::entries Helper for parsing entry-bundle tiles.
TlogTilesPendingLogEntry, TlogTilesLogEntry tlog_tiles::entries Default c2sp.org/tlog-tiles entry-bundle impl. Co-located with the trait it implements.

Crate has publish = false. Deps: length_prefixed, serde, sha2, tlog_checkpoint, tlog_core, tlog_tiles.

What stays in tlog_tiles

Just tile.rs — the c2sp.org/tlog-tiles HTTP wire format itself (Tile, TlogTile, PathElem, TileReader, TileHashReader, TlogTileRecorder, PreloadedTlogTileReader).

Production deps shrink to just tlog_core. length_prefixed, serde, sha2 dropped entirely; base64/url retained only as dev-deps for the CT integration test in lib.rs.

End state of #230

After slices 1–3 ship, each spec crate is aligned with the C2SP slug it implements:

  • tlog_core → RFC 6962 Merkle math + draft-ietf-plants-merkle-tree-certs subtree proofs.
  • tlog_checkpoint → c2sp.org/tlog-checkpoint signed-note format.
  • tlog_tiles → c2sp.org/tlog-tiles HTTP wire format.
  • tlog_entry → internal worker/spec interface (publish = false).

Migration

Every consumer of the moved symbols (bootstrap_mtc_api, bootstrap_mtc_worker, ct_worker, generic_log_worker, integration_tests, static_ct_api) now imports from tlog_entry directly.

bootstrap_mtc_worker and ct_worker no longer depend on tlog_tiles at all (they were only pulling it in for the trait definitions).

Stats

25 files changed, +109 / −44 (vs slice-2 head). The entries.rs move is git mv with 87% similarity (the diff is the new module doc-comment header + the tlog_tiles::PathElem import).

Pre-push checks

All four pass:

  • cargo clippy --workspace --all-targets -- -Dwarnings -Dclippy::pedantic
  • cargo test (33 test result blocks ok, 2 more than slice 2 from tlog_entry's relocated test_parse_tile_entry)
  • cargo fmt --all --check
  • cargo machete

Closes #230.

Slice 3 of #230. The traits and helpers that lived in
`tlog_tiles/src/entries.rs` aren't part of the c2sp.org/tlog-tiles
HTTP wire format \u2014 they're a worker-side abstraction that
`generic_log_worker` consumes and that the various per-application
data types (CT entries, MTC certificates, etc.) implement.

Putting them in any one of those crates creates a dependency cycle:
`generic_log_worker` already depends on `static_ct_api` and
`bootstrap_mtc_api`, so moving the trait definitions to
`generic_log_worker` would force the spec-level data types to depend
on a worker crate. Solution: a new internal crate `tlog_entry`
(`publish = false`) that holds the traits + the c2sp.org/tlog-tiles
default entry-bundle implementation, and that every spec crate plus
`generic_log_worker` depends on.

What moves to `tlog_entry`:

- `PendingLogEntry`, `LogEntry` traits (the worker / spec interface).
- `PendingLogEntryBlob` (DO storage shape).
- `LookupKey`, `LOOKUP_KEY_LEN` (cache/dedup key).
- `TileIterator` (helper for parsing entry-bundle tiles).
- `TlogTilesPendingLogEntry`, `TlogTilesLogEntry` \u2014 the default
  c2sp.org/tlog-tiles entry-bundle implementation. Co-located with the
  trait it implements; no current worker uses this directly but
  `bootstrap_mtc_api` wraps `TlogTilesPendingLogEntry` as a field,
  and the upcoming `ietf_mtc_worker` will use it too.

What stays in `tlog_tiles`:

- Just `tile.rs`: the c2sp.org/tlog-tiles HTTP wire format (`Tile`,
  `TlogTile`, `PathElem`, `TileReader`, `TileHashReader`,
  `TlogTileRecorder`, `PreloadedTlogTileReader`).
- The crate now matches its spec slug exactly. Production-deps
  shrunk to just `tlog_core`; `length_prefixed`, `serde`, `sha2`,
  `base64`, `url` are gone (`base64` / `serde` / `url` retained as
  dev-deps for the CT integration test in `lib.rs`).

Migration: `bootstrap_mtc_api`, `bootstrap_mtc_worker`, `ct_worker`,
`generic_log_worker`, `integration_tests`, `static_ct_api` now
import `LogEntry`/`PendingLogEntry`/etc. from `tlog_entry` directly.
`bootstrap_mtc_worker` and `ct_worker` no longer depend on
`tlog_tiles` at all (they were only pulling it in for the trait
definitions).

This closes the migration plan in #230. Slices 1\u20133 together leave
each spec crate aligned with its C2SP slug:

- `tlog_core` \u2192 RFC 6962 Merkle math + draft-ietf-plants-merkle-tree-certs
  subtree proofs.
- `tlog_checkpoint` \u2192 c2sp.org/tlog-checkpoint signed-note format.
- `tlog_tiles` \u2192 c2sp.org/tlog-tiles HTTP wire format.
- `tlog_entry` \u2192 internal worker/spec interface (`publish = false`).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant