Api Dto Laravel Package

Technical Evaluation

Architecture fit

• Unchanged. roadrunner/api-dto is not an application-layer library. It is the PHP-side representation of the RoadRunner (Go) server's protobuf API — the wire contract for the RPC channel between a PHP worker and the rr binary. It belongs to the infrastructure tier, not the domain tier.
• Fit is binary: it is load-bearing if you run Laravel Octane with the RoadRunner driver (or use spiral/roadrunner-http, -jobs, -kv, -metrics, -websockets directly). It has essentially zero relevance for FPM/nginx deployments or Swoole-based Octane.
• Where it fits, application developers should never import these classes. They are consumed by the RR transport/worker packages; direct usage only makes sense if you are writing a custom RPC service, a custom interceptor, or a Go/PHP plugin that speaks the RR protocol.
• The rename does not change the tier, the consumer set, or the "do not touch from application code" rule. It changes identity, not architecture.
• Note: the prior assessment already referred to the package by its new name roadrunner/api-dto ahead of this release; v2.1.0 makes that name official. The substantive technical evaluation is therefore unchanged — what changes is the dependency-management plan around it.

Integration feasibility

• Mechanically still trivial at the code level: no service provider, no config publish, no migrations, no runtime configuration. Autoload-only. The release contains no protobuf/DTO changes — a package rename plus a README refresh. The wire contract is byte-identical to v2.0.0, so there is no decode-compatibility risk in this bump.
• Feasibility is now gated on dependency identity rather than code. A Composer package rename is not expressible as a version constraint, so this "minor" 2.1.0 bump is a breaking change for every explicit require and every lockfile that names the old package. Treat it as a major.
• The blocking question is upstream sequencing: the spiral/roadrunner-* packages must themselves have released versions requiring the new name before the DTO rename can land transitively. Until they do, an explicit require of roadrunner/api-dto risks installing both names side by side.
• Regeneration (protoc/buf toolchain, ext-protobuf) remains an out-of-scope escape hatch, not a normal workflow.

Technical risk

• Package rename / dependency identity (high, new): the dominant new risk. Version numbers do not communicate it; automated bump tooling ("minor update available") will silently attempt it. Any pinned constraint, SBOM entry, allowlist, internal doc, or composer why reference against the old name goes stale in the same change.
• Split-brain install (high, new): if the old and new names are both resolvable in the tree, Composer maps two PSR-4 roots onto the same generated class names. Class resolution is then decided by autoload ordering — non-deterministic, environment-dependent, and capable of producing subtly wrong serialization rather than a clean error. This is the one genuinely dangerous failure mode introduced by the release.
• Namespace ambiguity (medium, new): confirm the change is Composer-name-only and does not relocate the PHP namespace. If the rename commit also moved RoadRunner\DTO\*, any direct consumer breaks with class-not-found — another argument for forbidding direct application usage.
• Supply-chain metadata reset (medium, new): download counts, dependent counts, package age, and any "is this established?" heuristic reset to zero under the new name. Policy tooling that gates on package age or popularity will newly flag a package your platform already depends on. The old name is likely to be marked abandoned, which will trip deprecation/abandonment scanners for a period.
• Version lock / lockstep coupling (high, carried over): the package's version is effectively a function of the RR binary version. Still the dominant recurring production risk across RR upgrades.
• Namespace/serialization churn between majors (medium, carried over): the RR proto API has historically moved namespaces and serialization runtimes across majors. Verify the namespace and runtime dependency of the exact tag you pin.
• Runtime dependency on protobuf (medium, carried over): confirm whether ext-protobuf is required or optional. If optional, the pure-PHP fallback works but is materially slower — a silent performance cliff rather than a hard failure.
• Metadata anomaly (carried over): the release date (2026-10-10) is again in the future relative to any normal evaluation window. Re-derive the actual latest tag from the repository and Packagist directly before deciding.
• Abandonment risk: still low-moderate, but the rename is exactly the "restructured rather than abandoned" scenario previously flagged — it has now partially occurred. The package was not folded into the worker packages, but its identity moved, which breaks pinned constraints in the same way.

Key questions

1. Are we actually running RoadRunner — via Octane's roadrunner driver, or via any spiral/roadrunner-* package directly? If no, this evaluation terminates: do not adopt.
2. What is the exact prior Composer name being replaced (confirm from the diff of commit 5246175, not from the repo URL), and is it being marked abandoned / does it ship a replace pointing at the new name?
3. Which released versions of spiral/roadrunner-http, -worker, -jobs, -kv, -metrics, -websockets require roadrunner/api-dto? Can we reach a tree where only the new name resolves?
4. Does the v2.1.0 diff show zero changes under the generated-code path (proto files, generated classes, PSR-4 mapping), and does the PHP namespace remain unchanged?
5. Which rr binary version (Docker image tag or downloaded artifact) is our baseline, and which api-dto tag corresponds to it?
6. Is ext-protobuf present in our base image and in every environment including CI and local dev? If not, are we accepting the fallback codec's throughput?
7. Do we have any custom RPC surface (custom service, interceptor, Go plugin) that justifies a direct dependency rather than a transitive one?
8. Who owns the RR binary/DTO upgrade pair, and is there a documented lockstep upgrade procedure that now includes the rename?
9. Which of our internal artifacts (SBOM, allowlists, security-scan exclusions, runbooks, dashboards keyed on package name) reference the old name?

Integration Approach

Stack fit

• Target profile: Laravel 10/11/12 on PHP 8.1+, served by RoadRunner through Laravel Octane, optionally extended with roadrunner-jobs (queue), roadrunner-metrics (Prometheus), roadrunner-kv, or roadrunner-websockets (Centrifugo).
• Outside that profile the package is inert. Do not add it "for completeness"; it buys nothing on FPM or Swoole.

Migration path

• Two distinct migrations must not be conflated: (a) adopting the RR runtime, and (b) the package rename. (b) is small, mechanical, and carries no wire-contract risk — which makes now, on v2.1.0, the cheapest possible moment to do it. Deferring only accumulates stale references and increases the chance of a split-brain install later.
• Preferred path (transitive): upgrade the spiral/roadrunner-* set to versions that require roadrunner/api-dto, let Composer resolve the new name, and never type it. This keeps the DTO governed as plumbing.
• Fallback path (explicit) only if a custom RPC surface exists: composer remove the old name, composer require roadrunner/api-dto:^2.1 in a single commit, then verify with composer why roadrunner/api-dto that exactly one provider exists.
• Never leave both names requirable. Add an explicit conflict entry against the old package name in composer.json so a stray transitive require hard-fails at resolve time instead of silently installing a duplicate PSR-4 root.
• The standard RR adoption path is unchanged: Octane with --server=roadrunner → Composer resolves spiral/roadrunner-* → those require the DTO transitively. The DTO appears in the lockfile without anyone typing its name, which is precisely why it must be governed explicitly.

Compatibility

• Maintain an explicit 3-way matrix in the repo: rr binary version ↔ roadrunner/api-dto version ↔ PHP/Octane version. Re-baseline the DTO column to v2.1.0 as part of this change. Pin the binary (image digest, not :latest) and pin the DTO to an exact or tightly bounded constraint under its new name.
• Because v2.1.0 carries no proto changes, it is compatible with the same rr binary as v2.0.0. This decouples the rename from any runtime upgrade — do not bundle them in one deploy.
• Verify the protobuf runtime requirement (google/protobuf or the RR-specific runtime package) resolves to a version compatible with the installed ext-protobuf; a mismatch manifests as a boot-time fatal, which is at least loud.
• Test the matrix in CI with the actual worker image, not a PHP-only runner — the runtime failure mode lives at the PHP↔Go boundary and will not reproduce without the binary.

Sequencing

1. Confirm RR adoption decision and pin the rr binary version/digest for all environments. (Unchanged; prerequisite.)
2. New: confirm the full spiral/roadrunner-* set has released versions requiring roadrunner/api-dto. If not, pause the rename — an explicit require against a still-old-name worker set creates the split-brain condition.
3. New: perform the rename as a standalone change, with the binary held constant. Update constraints, regenerate the lockfile, add the conflict against the old name.
4. New: verify composer why roadrunner/api-dto reports exactly one provider, and grep the installed vendor tree for the old package directory to confirm it is absent.
5. Add a CI gate that fails if the locked DTO version or name diverges from the approved baseline (a lockfile diff assertion against both names is sufficient).
6. Add a smoke test that exercises a real RPC round-trip against the pinned binary (HTTP request through the worker, plus one jobs/metrics call if used).
7. Only after that, consider a direct require — and only if a custom RPC service or plugin exists.
8. Roll out to staging with a canary worker pool before production; upgrade binary and DTO in the same deploy except for step 3, which ships alone.
9. Sweep internal artifacts — SBOM, allowlists, scan exclusions, runbooks, dashboards — for the old name.

Operational Impact

Maintenance

• Day-to-day: near zero. Generated code, no configuration, no application-level API to maintain. Genuinely low-touch.
• The rename adds a one-time cost, not a recurring one: a single coordinated constraint/lockfile change across the fleet, plus an artifact sweep. Estimate half a day for the platform owner including verification.
• Release-coupled: non-zero. Every RR binary upgrade implies a DTO review. Budget a small recurring line item (roughly an hour per RR upgrade) for the platform owner to walk the matrix and run the round-trip smoke test. Add the name and version to that checklist so the rename cannot regress.
• Do not fork the protos. A fork converts a free transitive dependency into an owned build pipeline (protoc/buf, codegen diffing, regeneration PRs) with no offsetting benefit for typical Laravel use.

Support

• Upstream only: GitHub issues on a low-traffic repo, plus the RoadRunner community channels. No commercial SLA, no security advisory process specific to this package, no CVE feed to subscribe to.
• The rename may split attention across two issue trackers and two Packagist entries for a transition period. Direct your team to the new repository for anything post-v2.1.0, and note that stale search results will point at the old name.
• Because the package is generated code, most "bugs" are actually contract mismatches and will be triaged upstream as integration issues. Your team owns the diagnosis. Ensure at least one engineer can read a protobuf decode error and map it back to a version skew — and now also recognize a duplicate-install symptom, which looks similar but is diagnosed at the Composer layer.

Scaling

• Serialization efficiency is a strength: protobuf binary framing is compact and fast relative to JSON for the worker↔server channel, and memory overhead is modest. The rename does not touch this.
• The scale lever remains ext-protobuf. With the C extension, encode/decode cost is negligible even at high RPS; without it, PHP-userland serialization becomes a measurable per-request tax that scales linearly with worker throughput. At Octane-class request volumes this is the difference between "invisible" and "a line item in the profiler."
• Nothing here changes horizontal scaling characteristics — worker count and RR pool configuration dominate. The DTO is not a scaling bottleneck; it is a scaling coefficient.

Failure modes

• Split-brain install (most likely consequence of this release): both package names present, duplicate PSR-4 mappings to identical class names, autoload-order-dependent resolution. Symptoms are inconsistent between workers or between deploys — the hardest class of bug to diagnose. Guard with the conflict entry and the vendor-tree grep.
• Stale constraint after the rename (likely): an old-name pin left in a service's composer.json or a CI image build script fails to resolve, or worse, quietly resolves the abandoned package alongside the new one.
• Policy/tooling false positive (likely, low impact): the new package name has zero recorded dependents and no history, so age- or popularity-gated scanners will flag it. Pre-empt with an explicit allowlist exception referencing this assessment.
• Namespace change if the rename went deeper than the Composer name: class-not-found at worker boot for any code referencing DTO classes directly. Confirm from the diff before rollout; verify at boot in staging.
• Version skew (carried over, still the classic RR failure): proto decode errors, worker boot failures, or unexpected EOF / invalid-message errors in rr logs immediately after a partial binary/DTO upgrade. Usually 100% failure at boot, which is preferable to partial degradation.
• Silent field loss (carried over): unknown-field handling across minor proto changes can drop data without erroring. Low probability for the core HTTP/KV paths, higher for jobs payloads and metadata.
• Missing ext-protobuf in one environment (carried over): silent codec fallback; no error, just slower. Detect via a startup assertion rather than discovering it in latency graphs.
• Opcache/preload misconfiguration (carried over): generated classes excluded from preload or stale in opcache after a deploy → intermittent autoload or stale-class behavior on long-lived workers. The rename makes a full opcache/preload flush mandatory, since the autoload classmap changes.
• Rollback: still safe and fast — revert the lockfile and the binary digest together. For the rename specifically, rollback means reverting to the old name, which is only clean if the split-brain guard was in place. Partial rollback of only one side remains the failure case to guard against.

Ramp-up

• Application developers: effectively zero. The package should be invisible; if a developer is importing RoadRunner\DTO\* in a controller, that is a code-review rejection.
• Platform/DevOps owner: moderate, and marginally higher than before. Requires comfort with the RR binary lifecycle, Composer constraint resolution against a pinned server, Composer-level package-identity mechanics (conflict entries, why, duplicate-install diagnosis), reading protobuf-level errors, and running the lockstep upgrade procedure. This is a one-person, half-day onboarding, not a team-wide skill.
• Given the low direct value and high coupling, the correct TPM posture is unchanged: do not adopt this package — adopt RoadRunner, and govern this package as a pinned transitive dependency of that decision. v2.1.0 does not change that verdict; it adds a bounded, mechanical, one-time rename migration that is cheapest to absorb now, while the wire contract is untouched. Its score reflects its nature as plumbing, not a deficiency; plumbing that silently changes identity is the actual risk.