Skip to content

Serialization.V2: remove [AkkaEnvelopePayload]; a property typed object is the serializer boundary - #8518

Merged
Aaronontheweb merged 2 commits into
akkadotnet:devfrom
Aaronontheweb:feature/serialization-v2-object-boundary
Sep 8, 2026
Merged

Aaronontheweb merged 2 commits into
akkadotnet:devfrom
Aaronontheweb:feature/serialization-v2-object-boundary

Conversation

@Aaronontheweb

Copy link
Copy Markdown
Member

Summary

Part of #8384. Implements Decision 20 of the OpenSpec design record (openspec/changes/messagepack-sourcegen-validation/design.md): [AkkaEnvelopePayload] is removed, and a property typed object is the serializer boundary on its own.

The static type of a property, after generic substitution, selects its encoding:

  • object or object?: the envelope frame, {1: serializerId, 2: manifest, 3: bytes}, decoded by whatever serializer owns the payload's runtime type.
  • an interface or abstract class with a type-level [AkkaUnion]: the union frame.
  • an interface or abstract class with no closed set: AKKASG003, with the hint "Declare a closed member set with [AkkaUnion], or type the property as object."
  • a concrete serializable type: inline.

A generic wrapper follows its type argument: Envelope<object> is a boundary, Envelope<AcceptCassette> is inline.

Changes

  • AkkaEnvelopePayloadAttribute deleted. XML docs on AkkaSerializer updated.
  • Generator: envelope-payload field kind now derives from SpecialType.System_Object on the substituted member type. Attribute detection removed.
  • AKKASG035 removed; its conflict cannot occur. The id stays a permanent gap.
  • New AKKASG038 (Error): a field-level [AkkaUnion] on an object-typed property is contradictory intent. Message: "Property '{0}' on type '{1}' is typed object, which is always an envelope payload boundary, but carries a field-level [AkkaUnion]. Type the property as the union's base type, or remove the attribute."
  • AKKASG003 polymorphic hint text updated as above. Ids, titles, and severities unchanged.
  • Retyped boundary fields: Artery SystemMessageEnvelope.Message (ISystemMessage to object), benchmark BenchmarkOuterEnvelope.Inner, and test fixtures; casts added at the consumers that needed them. The envelope nesting-depth guard is untouched.

Why

The attribute only ever added a static type to a boundary field. On dev, eight usages existed: four already object, two interfaces in a DTO and a spec, two concrete envelope types in nesting tests. All are DTO mirrors or fixtures, where retyping costs almost nothing. Same principle as the rest of the design: the closed set comes from the type, and the open case is explicit because the author wrote object.

Compatibility

No wire-format change: emitted code for an envelope field is byte-identical, and no golden-output or wire-snapshot file changed. The attribute never shipped in a release, so no BREAKING_CHANGES_V1.6.md entry. This must land before the first 1.6 beta; after that it would be a breaking change. Akka.Serialization.V2 is not covered by the API approval suite, and the retyped Artery type is internal; the approval tests pass unchanged.

Testing

dotnet test src/core/Akka.Serialization.V2.Tests -c Release: 268 passed, 0 failed (two AKKASG035 tests removed, one AKKASG038 test added). Akka.Remote builds; ArteryControlMessageSerializerSpec 32/32. Benchmarks build.

Follow-up

The user guide (#8514, merged) documents the attribute as it shipped before this PR and lists this removal under planned changes. A docs PR updates the envelope-payloads section once this merges.

…ct is the serializer boundary

Part of akkadotnet#8384 (Decision 20 in the OpenSpec design record).

- A property whose static type, after generic substitution, is object (or object?)
  is the envelope-payload boundary; no attribute is needed
- AkkaEnvelopePayloadAttribute and AKKASG035 are removed
- New AKKASG038: a field-level [AkkaUnion] on an object-typed property is an error
- AKKASG003 hint now reads: declare a closed member set with [AkkaUnion], or type
  the property as object
- Artery's system-message envelope, the benchmark envelope, and test fixtures are
  retyped to object; emitted code and wire format are unchanged
@Aaronontheweb Aaronontheweb added serialization akka.net v1.6 Akka.NET v1.6-related issues labels Sep 7, 2026

@Aaronontheweb Aaronontheweb left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Aaronontheweb
Aaronontheweb enabled auto-merge (squash) September 8, 2026 21:06
@Aaronontheweb
Aaronontheweb merged commit 6775212 into akkadotnet:dev Sep 8, 2026
13 of 15 checks passed
Aaronontheweb added a commit that referenced this pull request Sep 8, 2026
…boundary (#8518) (#8520)

Part of #8384. Updates docs/articles/serialization/source-generated-serialization.md
so it matches dev after #8518: a property typed object is the serializer boundary,
[AkkaEnvelopePayload] is gone, AKKASG035 is retired, AKKASG038 is documented, and
an object element inside a collection is listed as a current limitation.
Aaronontheweb added a commit to Aaronontheweb/akka.net that referenced this pull request Sep 11, 2026
akkadotnet#8518; object-typed payloads are the boundary

akkadotnet#8518 (6775212) removed AkkaEnvelopePayloadAttribute from Akka.Serialization.V2 - a
property whose static type is object (or object?) is now the envelope-payload boundary
by itself, with no attribute required. This left two sites in
ReliableDeliveryMessagePackSerializer.cs referencing the deleted attribute:
SequencedMessageWire.Payload and MessageSentWire.Payload, both already typed object?.
Drop the attribute, keep the object? typing, and update the two doc comments that
described the old attribute-based mechanism.

No wire-format or generated-code change; only the source-gen input annotation moved.
Verified: Akka.Cluster and Akka.Cluster.Tests build clean under -warnaserror with no
new AKKASGxxx diagnostics; ReliableDeliveryMessagePackSerializerSpecs (82 tests) and the
full Akka.Cluster.Tests Serialization filter (154 tests, includes the id 36 -> 76
classic-serializer fork) pass; Akka.Benchmarks builds clean.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

akka.net v1.6 Akka.NET v1.6-related issues serialization

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant