Etcd Discovery Laravel Package

Technical Evaluation

Architecture fit. This package couples service registration/discovery to Workerman's long-running event-loop process model, while Laravel's dominant runtime is short-lived PHP-FPM request handling. Those are structurally different lifetimes: registration, TTL lease keepalive, and graceful deregistration are long-lived concerns, whereas a Laravel request has no stable identity beyond the pod/VM it runs on. The package therefore fits cleanly only as a sidecar-style worker process launched alongside each Laravel instance (e.g., an Artisan command booting a Workerman worker), not embedded in request or queue lifecycles. If the team already runs webman or Workerman, fit is high; on stock FPM it adds a new runtime to operate.

Integration feasibility. Composer installation is likely trivial; the real question is API surface. A viable integration requires the package to expose (a) a registration client with explicit lease/TTL control, (b) a resolver usable from a normal FPM request (query + cache), and (c) a deregistration hook callable from SIGTERM handling. Whether the package's classes are decoupled from Workerman\Worker or assume a running event loop is the single biggest unknown. Etcd v3's native API is gRPC, which PHP handles poorly without ext-grpc + protobuf; many PHP packages fall back to the v3 HTTP/JSON gateway or the deprecated v2 API. That transport choice determines TLS, RBAC, and auth support, and it must be confirmed before committing.

Technical risk. High, driven by ecosystem signals rather than code quality: 10 stars, zero dependents, single-vendor origin, no visible community. Vendor abandonment is the base case a TPM should plan for, meaning internal ownership of a vendored fork. Secondary risks: the release date (2026-10-23) is in the future, which is a metadata anomaly suggesting an unaudited release process — verify tags, changelog, and CI before trusting versioning. Lease keepalive under network partition is the hardest correctness problem in any discovery client and is the most likely to be under-tested. If the target environment is Kubernetes, this package is largely redundant given native Endpoints/DNS discovery.

Key questions.

• Which etcd API version and transport (gRPC, HTTP gateway, v2), and does it support TLS/mTLS, auth, and namespaced prefixes?
• Can registration and resolution be used outside a Workerman worker, or is the event loop mandatory?
• What are the lease/TTL semantics, keepalive retry behavior, and deregistration guarantees on SIGTERM?
• Is there a watch API, or polling only? What is the reconnect/backoff strategy?
• PHP and Workerman version matrix; required extensions (pcntl, posix, grpc, protobuf)?
• License terms and any maintainer commitment, issue response history, test coverage, CI status?
• Is the target deployment bare-metal/VM/self-managed containers, or Kubernetes (where this is unnecessary)?

Integration Approach

Stack fit. Target Laravel 10–12 on PHP 8.1+ with Workerman 4.x/5.x. Keep the Laravel app on FPM/Octane unchanged; run the package as a supervised singleton process per instance (supervisor or systemd unit invoking php artisan etcd:register). The worker registers the instance's address with a short TTL and refreshes it; the FPM side consumes a resolver that reads from a local cache (Redis or file) refreshed by watch or short-interval poll. Do not let FPM requests talk to etcd directly.

Migration path. Phase 0: stand up a 3-node etcd cluster in staging and PoC a single non-critical service. Phase 1: wrap the package behind an internal ServiceRegistry interface with register, deregister, resolve, and watch methods, so Consul, etcd HTTP gateway, or static config can be swapped without touching call sites. Phase 2: roll out to two or three services with static-config fallback behind a feature flag. Phase 3: make it the default only after runbooks and alerting exist. Never remove the static/DNS fallback.

Compatibility. Verify etcd server version (3.4/3.5) parity with the client, and that the PHP extension set is available in the base image. Watch for Octane/Swoole conflicts — two event loops in one process is a debugging trap; keep the registration worker in a separate process. If already on Kubernetes, prefer native service discovery and treat this package as out of scope.

Sequencing.

1. Confirm transport, etcd version, and auth requirements against a real cluster.
2. Build the ServiceRegistry abstraction and the sidecar Artisan command with health-check gating (register only after the app passes readiness).
3. Add resolve-side caching with TTL and stale-while-revalidate semantics.
4. Add SIGTERM/SIGINT handlers that deregister before exit, plus a startup self-check.
5. Instrument registration success/failure, key age, and resolve cache hit rate.
6. Define and rehearse the rollback: flip the feature flag, fall back to static config, drain etcd.

Operational Impact

Maintenance. Assume you will fork and vendor this. Pin the version, mirror the repository internally, and budget roughly 0.1–0.2 FTE of platform engineering to track PHP, Workerman, and etcd upgrades and to patch keepalive edge cases. The anomalous future release date should be resolved before pinning — confirm tags and changelog integrity.

Support. No vendor SLA; support is GitHub issues on a 10-star repository, so response times are effectively unbounded. The escalation path is internal: whoever owns the fork owns production incidents. Document that explicitly before adoption.

Scaling. Etcd is a control plane, not a data store — it comfortably handles hundreds to low thousands of service instances with 10–30s TTLs, but watch-stream count and lease churn are the limits to monitor. The PHP side is cheap: one small Workerman process per instance. The real scaling hazard is read amplification — resolution must be cached, or every Laravel request becomes an etcd query and the cluster becomes a hard dependency of your request path.

Failure modes.

• Etcd unreachable at boot: decide fail-open (static config, degraded discovery) versus fail-closed. Fail-closed turns a control-plane outage into a full outage.
• Ungraceful termination (OOM kill, node loss): stale entries persist until TTL expiry; keep TTLs short and pair with active health checks.
• Workerman process crash: silent deregistration after TTL with no application error — alert on missing keys per instance.
• Etcd leader election or defrag: transient write failures; the keepalive loop must retry with backoff, not exit.
• Watch stream reconnect storms after an etcd restart; cap concurrency and jitter backoff.
• Clock skew inflating or truncating effective TTLs; require NTP and monitor drift.
• Phantom healthy instances during network partitions — the classic discovery failure, mitigated by server-side health checks, not just client heartbeats.

Ramp-up. One to two days for a mid-level PHP developer to absorb Workerman's process model and etcd concepts (leases, revisions, watches). Roughly one week to production-ready including the wrapper, tests, dashboards, and runbooks. Add etcd operator knowledge — quorum, backup/restore, defragmentation — which is a distinct skill from Laravel operations; if no platform team owns etcd, that cost lands on the application team and should be priced in before the build-vs-buy decision.