Skip to content

refactor: centralise connection-options (mTLS / gRPC transport / AWS SigV4) behind one seam instead of magic metadata markers #445

Open

Description

@thomas-stegemann

Problem

Several connection/request-level features are woven into every protocol plugin's connect/invoke/channel method via "magic" metadata-string markers plus repeated parse-then-strip boilerplate. This pushes feature complexity into the shared connection path that discovery, invoke, mock, and the normal workbench all traverse — even when the feature isn't in use. It's the anti-pattern of a rail/feature making the actual connection more complicated for everyone.

The good pattern (already in the codebase — the model to follow)

Mock / record / schema are cleanly isolated as separate extension classes implementing extension interfaces, in Mock/ subfolders — the connection methods never mention them:

  • IBowireMockSchemaSource, IBowireMockHostingExtension, IBowireMockLiveSchemaHandler
  • e.g. ProtobufMockSchemaSource, OpenApiMockSchemaSource, GraphQlMockSchemaSource, RestMockHostingExtension, GrpcMockHostingExtension

The active security probes (#395–#399) also follow this now: probes needing capabilities the plugin doesn't expose (MQTT will + ungraceful drop, WS permessage-deflate) bring their own connection inside the security-scanner package and touch zero shared plugin code.

The concerning pattern (this issue)

Feature concerns threaded into the shared connection path as magic metadata markers, with the same parse+strip boilerplate duplicated across methods:

  • gRPC — markers __bowireMtls__, __bowireGrpcTransport, __bowireQuery__. Every entry point repeats:
    var mtlsConfig = MtlsConfig.TryParseFromMetadata(metadata);
    var transportMode = GrpcChannelBuilder.ResolveMode(metadata);
    var afterMtls = mtlsConfig is null ? metadata : MtlsConfig.StripMarker(metadata);
    var sanitisedMetadata = GrpcChannelBuilder.StripTransportMarker(afterMtls);
    in BowireGrpcProtocol.InvokeAsync / InvokeStreamAsync / InvokeStreamWithFramesAsync and GrpcBowireChannel (4× the same 4 lines).
  • REST — __bowireAwsSigV4__ (RestInvoker.AwsSigV4MarkerKey) special-cases requests carrying the marker.
  • WebSocket — inline mtlsConfig + trustLocalhostCert handling in WebSocketBowireChannel.CreateAsync.

These are legitimately connection-intrinsic concerns (transport auth, transport mode, request signing) — unlike a rail's own probes — so they belong near the connection. The problem is the implementation: magic strings + duplicated resolve/strip logic in every method, rather than one clean seam.

Proposal

Introduce a single connection-options resolution seam per plugin (or a shared helper) that resolves the metadata markers once into a typed connection-options object and strips them once, so each plugin method calls one helper instead of repeating 4 lines × N methods:

// one call, typed result, markers stripped once
var (options, appMetadata) = GrpcConnectionOptions.Resolve(metadata);
// options.Mtls, options.TransportMode ... ; appMetadata is the caller's real headers

Consider replacing the stringly-typed __bowire*__ markers with a typed side-channel so metadata carries only real application headers and connection options travel separately.

Constraints (the principle this enforces)

  • A rail/feature builds on the shared connection concept; it must not complicate the shared connection interface. Features that are not connection-intrinsic (security probes, mock, record) own their own connections / live as isolated extensions — already the rule.
  • The workbench must keep working without any rail. This refactor must not change externally-observable behaviour for a plain connect/invoke.

Acceptance

  • gRPC mTLS + transport-mode resolved/stripped through one seam, called once per method (no duplicated 4-line block)
  • REST AWS-SigV4 marker handling folded into the same connection-options seam (not an ad-hoc special case)
  • WebSocket mTLS / trust-localhost handling expressed through the same shape
  • Magic __bowire*__ metadata strings removed from the app-header path (typed side-channel or centralised constants), so metadata seen by plugins is real headers only
  • No behaviour change for a plain connect / invoke / discover (regression-covered)

Related

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

  • Status
    Backlog

Relationships

None yet

Development

No branches or pull requests

Issue actions