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:
        -> MiddlewarePipeline (execute middleware stack)
           -> SchemaValidator (optional, if handler provides schemas)
           -> HookManager (fire BEFORE_HANDLER)
           -> 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 -> [middleware wraps:] -> 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
    }
}

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).

OpenRPC Export

Generate machine-readable OpenRPC specification:

php bin/generate-docs.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'];
    }
);