[ziflex]

This pull request updates the Ferret Wire client and documentation to clarify ownership, lifecycle, and security for logical and transport connections. It introduces a clear distinction between managed and caller-owned gRPC connections, improves teardown and error handling, and updates the API for clarity and safety. The documentation is extensively revised to reflect these changes, including new examples and security guidance.

API and Ownership Model Changes:

• The client now distinguishes between managed (New) and borrowed (From) gRPC connections, updating API names and documentation accordingly. The connectionHandle struct and newConnection function are updated to optionally own transport teardown and to handle startup cancellation, stream errors, and resource cleanup more robustly. ([[1]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09L17-R18), [[2]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R41-R126), [[3]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R166-R178), [[4]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09L169-R200), [[5]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R267-R287), [[6]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R298-R311))
• The client API now includes From, Option, and transport option factories, and removes previous lower-level handles and options, resulting in a breaking change for constructors. ([README.mdL173-R249](https://github.com/MontFerret/wire/pull/16/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L173-R249))

Documentation Updates:

• The README.md is rewritten to clarify the responsibilities of host and client applications, the difference between New and From, and the lifecycles of logical and transport connections. New examples are provided for both managed and caller-owned transports, and shutdown/cleanup semantics are explained in detail. ([[1]](https://github.com/MontFerret/wire/pull/16/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L3-R15), [[2]](https://github.com/MontFerret/wire/pull/16/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L26-R26), [[3]](https://github.com/MontFerret/wire/pull/16/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L62-R158), [[4]](https://github.com/MontFerret/wire/pull/16/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L104-R182))
• Security guidance is expanded, including how to configure TLS/mTLS, authentication/authorization, and the implications of transport choices. The documentation clarifies that Wire does not provide default endpoints or credential management and that hosts are responsible for security policy. ([README.mdL193-R291](https://github.com/MontFerret/wire/pull/16/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L193-R291))

Codebase Improvements:

• The newConnection function now accepts an optional transportClose callback, which is invoked during teardown if the client owns the transport, ensuring proper cleanup. ([[1]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R41-R126), [[2]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R298-R311))
• Error handling is improved for connection setup, teardown, and stream monitoring, including handling of startup cancellation and stream errors. ([[1]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R41-R126), [[2]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R166-R178), [[3]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09L169-R200), [[4]](https://github.com/MontFerret/wire/pull/16/files#diff-bd3a55a72186f59e2e63efb4951573b2f9e4a7cc98086e922b0859f8ccc1dd09R267-R287))
• Tests are updated to use the new newConnection signature. ([client/client_test.goL436-R436](https://github.com/MontFerret/wire/pull/16/files#diff-57cdc3e29d0ef725a50897a4fbd1c4f76353429fa66d3a785dcbc17dcd7b6f31L436-R436))

[Copilot]

Copilot review overview

🔵 Needs a closer look

The cross-cutting security and concurrent lifecycle changes require final human review and executed race/integration validation.

Review effort: Balanced
Findings: None

What changed in this PR

Updates Wire’s public client/server APIs with explicit transport ownership, managed serving, stronger lifecycle handling, and host-configured security.

Changes:

• Adds owned client.New and borrowed client.From construction.
• Adds managed server Run, TLS credentials, middleware, and shutdown coordination.
• Expands lifecycle, security, integration tests, benchmarks, and documentation.

Review notes: Static review only; tests and benchmarks were not executed. The supplied diff received a complete self-review.

File	Description
test/​securityfixture/​token.go	Adds token authentication fixtures.
test/​securityfixture/​tls.go	Adds local TLS certificate fixtures.
test/​integration/​security_test.go	Tests authenticated mTLS round trips.
test/​integration/​README.md	Documents security and ownership coverage.
test/​integration/​owning_constructor_test.go	Tests owned-channel lifecycle contracts.
test/​integration/​metadata_test.go	Migrates borrowed construction to From.
test/​integration/​lifecycle_test.go	Covers both ownership modes.
test/​integration/​harness/​transport.go	Observes owned socket closure.
test/​integration/​harness/​harness.go	Adds owned-transport harness mode.
test/​integration/​constructor_benchmark_test.go	Benchmarks owned construction.
test/​ferret/​README.md	Updates native-suite API usage.
test/​ferret/​harness_test.go	Migrates server and client constructors.
test/​ferret/​go.sum	Updates nested dependency checksums.
test/​ferret/​go.mod	Updates nested options dependency.
server/​serving_listener.go	Retains listener errors across shutdown.
server/​serving_listener_test.go	Tests listener closure failures.
server/​serving_context.go	Adds serving error helpers.
server/​server.go	Implements managed serving and shutdown.
server/​server_limits_test.go	Migrates limit tests to server.New.
server/​security_test.go	Tests TLS, middleware, and limits.
server/​security_options_test.go	Tests security option behavior.
server/​runtime_optimization_presence_test.go	Uses borrowed client construction.
server/​runtime_contract_test.go	Defines the new public server surface.
server/​runtime_adapter_benchmark_test.go	Migrates benchmark construction.
server/​run_test.go	Exercises managed serving lifecycle.
server/​run_options.go	Adds managed shutdown timeout options.
server/​options.go	Adds credentials and interceptor options.
server/​option_validation_test.go	Tests aggregated option validation.
server/​metadata_benchmark_test.go	Adds middleware-chain benchmarks.
server/​managed_fixture_test.go	Adds managed server test fixtures.
server/​limits.go	Adopts aggregate limit validation.
server/​internal/​core/​errors.go	Removes obsolete missing-resource helper.
server/​internal/​core/​connection_registry.go	Retains concurrent cleanup results.
server/​internal/​core/​connection_registry_test.go	Tests shutdown cancellation and failures.
server/​integration_test.go	Migrates public constructors.
server/​doc.go	Documents serving and security behavior.
README.md	Rewrites public API and security guidance.
go.sum	Adds options dependency checksums.
go.mod	Adds go-options dependency.
docs/​security.md	Adds comprehensive security configuration.
docs/​protocol.md	Updates listener ownership semantics.
docs/​client.md	Documents New/From ownership.
docs/​architecture.md	Documents lifecycle and security architecture.
client/​transport_security_test.go	Tests TLS and credential propagation.
client/​transport_options_test.go	Tests client option validation.
client/​transport_lifecycle_test.go	Tests owned transport teardown.
client/​runtime.go	Moves construction into dedicated API.
client/​runtime_contract_test.go	Defines the new client surface.
client/​ownership_test.go	Updates internal constructor calls.
client/​options.go	Adds transport option factories.
client/​lifecycle.go	Retains context values during cleanup.
client/​lifecycle_test.go	Updates lifecycle construction.
client/​doc.go	Documents channel ownership.
client/​constructor.go	Implements New and From.
client/​constructor_test.go	Tests borrowed constructor behavior.
client/​client.go	Adds owned transport teardown.
client/​client_test.go	Migrates test constructors.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.