Skip to content

feat(data-contracts): add per-link codec selection#183

Open
thaodt wants to merge 2 commits into
aimdb-dev:mainfrom
thaodt:feat/178-perlink-codec-section
Open

feat(data-contracts): add per-link codec selection#183
thaodt wants to merge 2 commits into
aimdb-dev:mainfrom
thaodt:feat/178-perlink-codec-section

Conversation

@thaodt

@thaodt thaodt commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

Description

Adds registration-time codec selection for individual inbound and outbound links, allowing the same record type to use different wire formats across heterogeneous transports.

For e.g., one record can use bounded postcard for an MCU/serial route while using JSON for an MQTT/cloud route, without introducing a runtime codec registry, lock or per-message lookup.

What changed

  • Added the format-neutral LinkCodec<T> trait.
  • Added LinkCodecBuilderExt::with_link_codec(codec) for inbound and outbound link builders.
  • Added LinkCodecRegistrarExt::{linked_from_with, linked_to_with} shorthand methods.
  • Added built-in codec markers:
    • link_codecs::Default
    • link_codecs::Json
    • link_codecs::Postcard<N>
  • Added the optional, no_std-compatible linkable-postcard feature.
  • Preserved connector-specific builder composition, including MQTT QoS and retain extensions.
  • Reused PR feat(linkable): add allocation-free postcard encode_into #180's route-local scratch buffer for bounded postcard encoding, with owned fallback when the configured capacity is too small.
  • Added complete last-selection-wins semantics: replacing a bounded codec with an owned-only codec clears the previous scratch serializer and prevents mixed wire formats on one route.
  • Kept the existing .linked_from() and .linked_to() APIs unchanged.
  • Updated the README, changelogs, feature matrix, benchmarks and design doc 045.

Performance

Codec selection is fused into the existing typed serializer/deserializer closures during registration. It does not add a runtime registry or lookup to the message path.

The allocation benchmark covers the codec over 10000 warmed iterations:

  • Direct Linkable::encode_into: 0 allocations / 0 bytes
  • Per-link Postcard<N>::encode_into: 0 allocations / 0 bytes
  • Allocator positive control: 1 allocation / 64 bytes

Oversized postcard payloads retain the existing owned allocation fallback for correctness.

Related Issue

Checklist

  • I have read the CONTRIBUTING.md document.
  • My code follows the project's coding standards.
  • I have added tests to cover my changes.
  • All new and existing tests passed (make check).
  • I have updated the documentation accordingly.

@thaodt thaodt requested a review from lxsaah as a code owner July 16, 2026 06:27
thaodt added 2 commits July 16, 2026 13:29
- add `LinkCodec` with builder and registrar overrides
- add feature-gated JSON and bounded postcard codecs
- preserve reusable scratch encoding with owned fallback
- verify MQTT extension composition and zero-allocation fast path
- update feature matrix, changelogs, README and design docs
@thaodt thaodt force-pushed the feat/178-perlink-codec-section branch from 784a5c4 to 30a9e6f Compare July 16, 2026 06:29
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.

[FEAT] Per-link codec selection for a single record type

1 participant