Architecture Notes

Design Principles

Request Flow

HTTP Request
  -> JsonRpcServer (HTTP facade)
  -> RequestReader (body extraction, gzip decoding, size limit)
  -> JsonRpcEngine (core, transport-agnostic)
     -> HookManager (fire BEFORE_REQUEST)
     -> JSON Decode (with depth limit)
     -> BatchProcessor (detect single vs batch, validate structure, enforce batch.max_items)
     -> AuthManager + RequestAuthenticator (extract credentials, authenticate, build UserContext)
     -> RateLimitManager (check rate limits)
     -> For each request:
        -> HookManager (fire BEFORE_HANDLER)
        -> SchemaValidator (optional, if handler provides schemas)
        -> MiddlewarePipeline (execute middleware stack around handler execution)
           -> MethodResolver (map method name to handler class+method)
           -> HandlerDispatcher + HandlerFactory (instantiate handler, invoke method)
           -> ParameterBinder (bind params to method arguments)
           -> HookManager (fire AFTER_HANDLER) -- fires inside handler execution
        -> Response building (success or error)
     -> HookManager (fire ON_RESPONSE)
  -> HttpResponse (JSON encode, optional ETag, optional gzip)

Lifecycle Guarantees

The execution order is formalized and tested. The following guarantees hold for every request:

Before middleware runs:

During middleware execution:

After middleware completes:

Hook execution order (per request):

BEFORE_REQUEST -> [auth hooks] -> [rate limit] -> BEFORE_HANDLER -> [schema validation] -> [middleware wraps: handler] -> AFTER_HANDLER -> ON_RESPONSE -> AFTER_REQUEST

What is NOT guaranteed before middleware:

Component Responsibilities

Core (src/Core/)

Config (src/Config/)

Protocol (src/Protocol/)

Http (src/Http/)

Dispatcher (src/Dispatcher/)

Auth (src/Auth/)

Middleware (src/Middleware/)

Validation (src/Validation/)

RateLimit (src/RateLimit/)

Log (src/Log/)

Cache (src/Cache/)

Doc (src/Doc/)

Support (src/Support/)

Error Handling Strategy

All errors are converted to proper JSON-RPC error responses:

In production mode (debug: false), stack traces and internal details are stripped from error responses. In debug mode, additional diagnostic data is included.

JSON serialization failures in response encoding are handled per-response: each response is encoded independently using JSON_THROW_ON_ERROR so one unserializable result does not affect other responses in a batch. A single failed response becomes a -32603 error with a diagnostic message, while other batch responses remain intact.

Documentation generators (OpenRpcGenerator, JsonDocGenerator) use JSON_THROW_ON_ERROR — encoding failures are surfaced as exceptions rather than silently replaced with empty JSON objects.

The FileRateLimiter uses JSON_THROW_ON_ERROR for persisting rate limit state — encoding failures surface as exceptions rather than silently corrupting state with empty JSON.

Extension Points

Custom Handler Factory (DI)

$server->setHandlerFactory(new class implements \Lumen\JsonRpc\Dispatcher\HandlerFactoryInterface {
    public function create(string $className, \Lumen\JsonRpc\Support\RequestContext $context): object {
        // inject dependencies before returning the handler instance
    }
});

Middleware

$server->addMiddleware(new class implements \Lumen\JsonRpc\Middleware\MiddlewareInterface {
    public function process(
        \Lumen\JsonRpc\Protocol\Request $request,
        \Lumen\JsonRpc\Support\RequestContext $context,
        callable $next
    ): ?\Lumen\JsonRpc\Protocol\Response {
        // pre-processing
        $response = $next($request, $context);
        // post-processing
        return $response;
    }
});

Custom Authenticator

Implement AuthenticatorInterface:

class MyAuth implements \Lumen\JsonRpc\Auth\AuthenticatorInterface {
    public function authenticate(string $token): ?\Lumen\JsonRpc\Auth\UserContext {
        // Custom auth logic
    }
}

For custom header parsing or non-standard credential extraction, implement RequestAuthenticatorInterface and register it through JsonRpcServer::setRequestAuthenticator().

Custom Rate Limiter

Implement RateLimiterInterface:

class RedisRateLimiter implements \Lumen\JsonRpc\RateLimit\RateLimiterInterface {
    public function check(string $key): \Lumen\JsonRpc\RateLimit\RateLimitResult {
        // Redis-backed single check
    }

    public function checkAndConsume(string $key, int $weight): \Lumen\JsonRpc\RateLimit\RateLimitResult {
        // Redis-backed atomic weighted check+consume
    }
}

An InMemoryRateLimiter is also available for testing or single-process use cases.

Explicit Procedure Descriptors

For advanced use cases where you want an explicit API contract instead of (or in addition to) handler auto-discovery:

use Lumen\JsonRpc\Dispatcher\ProcedureDescriptor;

$registry = $server->getRegistry();

$registry->register('math.add', MathHandler::class, 'add', [
    'description' => 'Add two numbers',
    'requiresAuth' => false,
]);

// Or using descriptor objects:
$registry->registerDescriptor(new ProcedureDescriptor(
    method: 'math.multiply',
    handlerClass: MathHandler::class,
    handlerMethod: 'multiply',
    metadata: ['description' => 'Multiply two numbers'],
));

Descriptor metadata is used by the documentation generators (including OpenRPC). Runtime request schemas from RpcSchemaProviderInterface are also reused by the JSON and OpenRPC generators when available.

For richer response contracts, explicit descriptor metadata may include resultSchema, and auto-discovered handlers may provide @result-schema {...} in method docblocks; both flow through to generated JSON/OpenRPC result definitions.

OpenRPC Export

Generate machine-readable OpenRPC specification:

php bin/generate-docs.php --config=./config.php --format=openrpc --output=docs/openrpc.json

Hooks

$server->getHooks()->register(
    \Lumen\JsonRpc\Support\HookPoint::BEFORE_HANDLER,
    function (array $context) {
        // Pre-processing logic
        return ['extra_data' => 'value'];
    }
);

Hooks run inline with request execution. By default, hook exceptions are isolated, logged, and skipped so later hooks and request handling can continue. Set hooks.isolate_exceptions to false if you need hook failures to abort the request.