README

Edge-only HTTP gateway for KislayPHP services. Route, apply lightweight edge policy, and forward requests without duplicating Core runtime behavior.

Installation

Via PIE (recommended):

pie install kislayphp/gateway:0.0.9

Add to php.ini:

extension=kislayphp_gateway.so

Role In The Stack

Gateway is the edge layer only.

• Gateway: route, optional edge auth, rate limit, circuit break, forward
• Core: request lifecycle, JWT state, tracing, async HTTP, business logic
• Discovery: resolve service name to healthy instance URL

Gateway does not reimplement Core's JWT state model or async HTTP engine.

Quick Start

<?php

$gateway = new Kislay\Gateway\Gateway();
$gateway->addRoute('GET', '/health', 'http://127.0.0.1:9008');
$gateway->listen('0.0.0.0', 9009);

while (true) {
    sleep(1);
}

Discovery Integration

<?php

$gateway = new Kislay\Gateway\Gateway();
$gateway->addServiceRoute('GET', '/api/users', 'user-service');
$gateway->registerService('user-service', [
    'http://127.0.0.1:9001',
    'http://127.0.0.1:9002',
]);
$gateway->listen('0.0.0.0', 9009);

while (true) {
    sleep(1);
}

Service route resolution order is:

1. native C++ service registry via registerService()
2. PHP setResolver() callback if configured
3. Discovery RPC when KISLAYPHP_RPC_ENABLED=1

For production, prefer registerService() so request threads stay on the native path.

Runtime Behavior

Request forwarding

Gateway forwards:

• method
• path and query string
• headers
• body
• Authorization
• X-Request-ID
• traceparent
• tracestate

Gateway generates X-Request-ID only when the incoming request does not provide one. Gateway preserves upstream X-Forwarded-For chains, forwards the incoming host, and derives X-Forwarded-Proto from the actual client-facing scheme.

Auth alignment

Gateway can do optional edge validation:

• shared bearer token via KISLAY_GATEWAY_AUTH_TOKEN
• JWT signature/expiry validation via KISLAY_GATEWAY_JWT_SECRET

In both cases, Gateway forwards the original Authorization header downstream and leaves jwt_valid / jwt_payload ownership to Core.

Resilience

Gateway keeps resilience lightweight:

• read timeout on upstream responses
• retry only for idempotent methods and only on pre-response upstream failures
• simple per-upstream circuit breaker with CLOSED / OPEN / HALF_OPEN
• thread-local upstream connection reuse for direct routes

Environment Variables

Notes

• listen() starts the server and returns; keep the process alive explicitly.
• Retry is intentionally narrow. Gateway is not a replacement for Core's async execution layer.
• registerService() is the recommended production service discovery path. It publishes a native registry snapshot and avoids PHP callbacks on the request path.
• On ZTS builds, PHP resolvers are rejected at listen() time. Use Discovery RPC or direct targets there.
• Rate limiting currently uses in-memory storage.

License

Licensed under the Apache License 2.0.