Eternet.Mediator.EndpointManifest.Generator 3.1.0

Eternet.Mediator.EndpointManifest.Generator

Analyzer package that emits the public Eternet.Mediator.Generated.EndpointManifestProvider carrier for mediator contract assemblies.

Use this package in *.Contracts projects together with:

• Eternet.Mediator.EndpointModel
• <EternetGenerateEndpointManifest>true</EternetGenerateEndpointManifest>

This package is intentionally narrower than Eternet.Mediator.Generator. It only carries the manifest-emission generator needed by contract packages, while runtime/controller generation remains in the broader mediator generator package.

The generator emits a manifest for any assembly that contains endpoint descriptors. ApiGatewaySourceService can still add source-service identity, but it is not required for manifest emission.

Services that can safely forward every gateway request to a fully isolated testing environment can add [assembly: ApiGatewayTestingSupport]. Services with partial support can instead add [ApiGatewayEndpointTestingSupport] to each supported endpoint contract or OData entity-set class. The generator records the selected scope in the manifest and reports compile-time error EM9012 if an assembly combines the global and endpoint-level modes.

Relative gateway routes are composed below their OperationNamespace. The generator reports warning EM9013 when a relative route already starts with that namespace because it would publish a duplicated path such as Networking/Networking/.... Remove the namespace segment from the route, or set IsRouteAbsolute = true when the declared route intentionally owns the complete public path.

New public contracts should mark the abstract endpoint contract with EndpointGroup, not GenerateEndpoint. GenerateEndpoint is server-only opt-in metadata.

EndpointManifestProvider.ManifestJson is intentionally public so source generators in consuming projects can read the manifest from metadata references during compilation. The sidecar file remains the preferred runtime/build artifact when the consuming tool is not a source generator.

Types marked with GenerateHttpClient, or nested inside a GenerateHttpClient container, are intentionally excluded from the emitted manifest because the current assembly consumes them as outbound descriptors instead of serving them.

For the current contract authoring model that feeds this generator, see ../docs/contracts-and-transport-authoring.md and ../docs/endpoint-manifest-ecosystem.md.

OData capability publication

[ContractCapability(Publish = false)] on an OData entity-set declaration omits its agent capability while preserving the OData model, HTTP descriptor, schema and generated client/server surface. Inherited publication decisions are honored; an explicit entity-set declaration overrides its inherited decision, including Publish = true. An entity set without a publication override retains the default publication behavior. This flag does not change endpoint authentication or authorization.

Client export contract decisions

The client export (EternetGenerateClientExport=true) is documented in ../../../docs/typescript/contract-export-v1.md. These decisions settle the review findings of issue #908:

When a whole-object standard [FromBody] request declares a JSON converter, the generated controller and HTTP client use that converter. Client export cannot infer an arbitrary converter's input wire shape and reports EMCX001 instead of publishing a schema based on CLR properties. The export is opt-in; the ordinary endpoint manifest remains available. Contracts needing client export require a future explicit, validated input-wire schema associated with the converter. That schema must distinguish secret-bearing transport input from any redacted serialization. Until that capability is implemented, keep such contracts on a previously supported transport path and preserve their existing validation; disabling or suppressing the diagnostic does not produce a reliable export.

• Enums are contracts of their declared members. Capability input.jsonSchema and the export keep the canonical enum names; neither describes the extra casings or integers that JsonStringEnumConverter also accepts. The export marks string enums whose converter allows integers with allowsIntegerValues: true, because such a converter also writes an undeclared value (for example (State)99) as a JSON integer.
• No shared Eternet host setup installs a global JsonStringEnumConverter; each service configures MVC JSON options itself, and some write enums as numbers. An enum serialized as JSON in an exported contract must therefore declare JsonStringEnumConverter<T> or JsonNumberEnumConverter<T> on the enum type, otherwise the export fails with EMCX010. Route, query, header and form bindings and dictionary keys do not need it.
• A projected DomainResult response whose type is also serialized as an ordinary DTO with a different wire shape is exported as <type id>@projection; types used only as responses keep their ids. EMCX007 checks every projection.
• FluentValidation rules come from the single public validator constructor, or from the rules common to all public constructors when there are several.
• Pause-capable pipelines describe their HTTP 202 PipelinePausedResponse outcome in response.paused.
• Item 13 (implicit requiredness of non-nullable query, header and form members) is not applicable yet: generated controllers are emitted without #nullable enable, so their reference parameters are nullable-oblivious, MVC infers no [Required], and the endpoint accepts the omission. Those bindings stay optional unless the member is required. It becomes applicable only if controller generation emits nullable annotations, which changes runtime validation of every generated endpoint and needs its own change.
• The PipelinePausedResponse projection ({ reason }) is registered after every DTO is known, under <type id>@projection when a [FromBody] PipelinePausedResponse member makes the plain id an ordinary DTO.
• A named type reached from a route, query, header or form binding is not treated as JSON; the host-dependent enum check (EMCX010) runs only for types a JSON use also reaches.

Sensitivity declarations

When the effective ContractCapability attribute explicitly supplies SensitiveInput or SensitiveOutput, the generated capability metadata includes sensitiveInputDeclared or sensitiveOutputDeclared, respectively, with the string value true. The corresponding safety property carries the declared value. Absence of the metadata key means that the declaration is unknown; historical manifests also lack these keys. The keys report source declarations, not an audit or authorization decision. The capability fingerprint includes each declared value so a declaration or change invalidates the previous fingerprint. Existing fingerprints remain unchanged when neither field is declared.