Repository navigation
Description
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:invar mtlsConfig = MtlsConfig.TryParseFromMetadata(metadata); var transportMode = GrpcChannelBuilder.ResolveMode(metadata); var afterMtls = mtlsConfig is null ? metadata : MtlsConfig.StripMarker(metadata); var sanitisedMetadata = GrpcChannelBuilder.StripTransportMarker(afterMtls);
BowireGrpcProtocol.InvokeAsync/InvokeStreamAsync/InvokeStreamWithFramesAsyncandGrpcBowireChannel(4× the same 4 lines). - REST —
__bowireAwsSigV4__(RestInvoker.AwsSigV4MarkerKey) special-cases requests carrying the marker. - WebSocket — inline
mtlsConfig+trustLocalhostCerthandling inWebSocketBowireChannel.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 headersConsider 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), sometadataseen by plugins is real headers only - No behaviour change for a plain connect / invoke / discover (regression-covered)
Related
- Surfaced during the v2.3 active-probe work (Active MQTT probes: retained-message poisoning + will-message abuse (PUBLISH-based) #395–gRPC stream fork-bomb / concurrent-stream limit probe #399); the security rail deliberately avoids this pattern by owning its own connections.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsBacklog
Activity