Json Rpc Laravel Package

Technical Evaluation

• Architecture fit: Unchanged. fguillot/json-rpc remains a narrow JSON-RPC client/server utility rather than a Laravel-native integration, best used behind an application-owned adapter for internal service-to-service calls, legacy RPC endpoints, control-plane APIs, or narrowly scoped command channels. Not a default choice for public APIs or platform-wide messaging.
• Integration feasibility: Composer installation is still straightforward, but v2.0 hardening increases the amount of behaviour the adapter must own: exception mapping now depends on whether a 500 carries a JSON-RPC error object (relayed) or non-RPC content (ServerErrorException), and response validation now rejects mismatched ids and non-answer JSON rather than returning null. These are improvements, but they are contract-visible and must be encoded in the adapter and tests.
• Release maturity (new): v2.0.0-beta2 is explicitly a preview: the API may still move before 2.0.0, and the release depends on an open PR (#29) on the 2.x branch. That is a schedule and stability risk, not a quality risk.
• Quality signals (materially improved): 366 tests, 100% line coverage enforced in CI, PHPStan at max level with no baseline, phpcs clean, exercised against real HTTP servers rather than mocks, and five rounds of adversarial review between betas. This shifts the risk profile from "undocumented edge cases" toward "pre-GA API churn." It does not eliminate low-adoption risk.
• Breaking changes (v2): Parameters are no longer coerced. A client sending ["5","3"] to function (int $a, int $b) now receives -32602 Invalid params. This will break existing deployments whose callers send loosely typed payloads, and it changes behaviour for both client and server modes. UPGRADE-2.0.md is now a required input to any plan.
• Security and robustness improvements: Cookies with control characters or separators are refused; deleted cookies (empty value, Max-Age=0, past Expires) are no longer replayed; answers carrying another request's id or non-answer JSON are refused, including per-call inside batches; truncated bodies are detected across stream, cURL and PSR-7 transports; compressed bodies are correctly distinguished from malformed payloads. These directly reduce replay/cookie-leak, response-confusion, and silent-null failure modes — relevant if the server component is ever exposed, though it does not substitute for authn/authz, rate limiting, and input validation.
• Transport behaviour changes: cURL no longer emits Expect: 100-continue, removing ~1s latency on requests above 1 MB; PSR-7 truncated bodies now raise ConnectionFailureException instead of a bare RuntimeException. Both are net positive but are observable changes for any existing retry/exception logic.
• Server-mode fixes: Variadic procedures accept named parameters, numerically named procedures can be registered via array helpers, and withAuthenticationHeader() parses scheme-prefixed headers (Basic <base64>). Small but real reductions in custom workaround code.
• Technical risk: Dominant risks are now (1) pre-GA instability and the open PR dependency, (2) the parameter-coercion break for existing callers, (3) PHP 8.4/8.5 CI targets raising the minimum-version question against the supported Laravel matrix, and (4) continued provenance ambiguity — the Composer name is fguillot/json-rpc while releases are published from matasarei/json-rpc. Low adoption (23 stars, 0 dependents) remains, though maintenance activity and release discipline are visibly stronger.
• Scope risk: Unchanged. Client mode is lower risk than server mode; public server exposure still requires authentication, authorization, validation, rate limiting, replay protection, and error-disclosure controls the library does not provide.
• TPM recommendation: Conditional, isolated dependency — unchanged in principle, but now wait for 2.0.0 GA or pin the beta with an explicit upgrade plan. Beta2 is good enough for a spike and contract-test harness; it is not a reason to relax the adapter boundary, and the coercion break means any v1 usage must be re-validated.
• Key questions: What is the minimum PHP version for 2.x, and does it fit the Laravel versions in the support matrix? When is 2.0.0 GA expected, and does it depend on merging PR #29? Do any existing callers rely on parameter coercion, and what is the remediation cost? Is the matasarei/json-rpc repository the authoritative source for the fguillot/json-rpc Packagist entry, and are dist archives signed/verifiable? Which mode (client vs server) is in scope? Who owns patching if upstream stalls? What is the fallback (native Laravel HTTP client or alternate library)?

Integration Approach

• Stack fit: Unchanged and now more important: bind to an application-owned contract such as JsonRpcClientInterface with a concrete adapter. Keep request construction, batch semantics, error-code translation, cookie handling, and response validation inside the adapter so domain code is insulated from the v1→v2 behaviour shifts.
• Configuration: Externalize endpoints, timeouts, retry policy, auth headers, TLS/proxy settings, compression expectations, and JSON-RPC version via Laravel config and env vars. Do not hard-code transport or Expect-header behaviour assumptions in call sites.
• Migration path: Treat this as a v1→v2 migration even if you have not shipped yet. Start from UPGRADE-2.0.md, inventory every parameter payload for coercion dependence, and build contract tests that assert both the strict -32602 case and the happy path. Exercise the new response-validation rules (id mismatch, non-answer JSON, batch partial failure) and the new exception split (ServerErrorException for non-RPC 500s) before promoting.
• Compatibility: Gate on the PHP minimum for 2.x against the Laravel/PHP matrix. Run Composer resolution, static analysis, and integration tests on the oldest and newest supported combinations. Re-check that the Composer target resolves to the same repository producing these release notes.
• Sequencing:
  1. Verify provenance: Packagist source/dist, tag integrity, license, maintainer continuity, and the matasarei vs fguillot relationship.
  2. Confirm PHP/Laravel version fit and whether 2.0 GA timing is acceptable; if not, stay on v1 and revisit.
  3. Run the coercion-impact audit and update contract tests.
  4. Build/upgrade the Laravel adapter, config surface, and exception mapping.
  5. Pilot in one low-risk integration; validate compression, cookie, timeout, and truncated-body paths against a real server.
  6. Add observability, retries, and failure mapping.
  7. Promote to a pinned stable release only after GA and accepted operational ownership.
• Exit path: The adapter must allow replacement by Laravel's HTTP client or another JSON-RPC library without changes to domain code — this is the main hedge against beta churn and low adoption.

Operational Impact

• Maintenance: Upstream activity and review discipline have improved (active 2.x branch, adversarial review rounds, strict CI gates), which lowers — but does not remove — the chance of needing an internal fork or patch set. Pin exact versions, avoid spread of direct package calls, and budget for a v2 GA upgrade.
• Beta churn: Expect further breaking changes before 2.0.0. Do not build dependent features on undocumented beta behaviour; keep version pinned and re-run the contract suite on each beta/RC.
• Support model: Internal ownership still required. Define an on-call owner for JSON-RPC failures, timeout/retry behaviour, and upstream changes. Bus factor and adoption remain low; do not rely on the maintainer for production incident response.
• Scaling: Client mode is effectively stateless and scales with the caller, with a small latency win from the removed Expect: 100-continue. Server mode still needs evaluation for concurrency, request-size limits, batch processing, rate limiting, and DoS exposure; if used, front it with Laravel middleware or a gateway.
• Failure modes: Timeouts, retries with duplicate side effects, malformed or truncated responses, id mismatches (now surfaced as errors rather than null), batch partial failures, JSON-RPC error-code ambiguity, version mismatch, auth expiry, TLS/proxy issues, and — new in v2 — strict-parameter -32602 rejections from previously tolerated callers. Map all of these into application-level exceptions, metrics, and runbooks.
• Security operations: The cookie-hardening and response-validation changes reduce known leak and response-confusion paths; keep dependency scanning in place and re-test after each beta in case of regression.
• Observability: Instrument latency, error rate by JSON-RPC code, timeout and retry counts, -32602 rates (proxy for coercion regressions), ServerErrorException vs relayed-error splits, and payload-size outliers. Log correlation ids without sensitive payloads.
• Ramp-up: Library ramp-up stays small; the new work is protocol-adjacent — strict typing expectations, upgrade-guide deltas, exception-split handling, and test fixtures for compression, cookies, and truncated bodies. Document these as onboarding material.
• TPM exit criteria: Adopt only when 2.0.0 GA is available (or a pinned beta is explicitly accepted), provenance is verified, the coercion impact is remediated, the adapter boundary is enforced, and the team accepts patching/support ownership. Reject if the package would become a broadly shared platform dependency without a maintained fork or clear replacement path.