folk-plugin-http

HTTP plugin for Folk — accepts connections via hyper and dispatches requests to PHP workers.

Status: in active development. See folk-spec for the roadmap.

Requirements

• Rust 1.85+
• folk-api (only dependency for plugin compilation)

Installation

# Cargo.toml
folk-plugin-http = "0.1"

Quick start

1. Add the plugin to folk.build.toml:

[build]
output = "my-folk"

[[plugin]]
crate_name = "folk-plugin-http"
version = "0.1"
config_key = "http"

2. Configure in folk.toml:

[http]
listen = "0.0.0.0:8080"
read_timeout = "10s"
write_timeout = "30s"

3. Write a PHP handler:

<?php
// app/Http/FolkHandler.php
use Folk\Sdk\Http\HttpModeHandler;
use Folk\Sdk\Http\HttpRequest;
use Folk\Sdk\Http\HttpResponse;

class FolkHandler implements HttpModeHandler
{
    public function handle(HttpRequest $request): HttpResponse
    {
        $response = new HttpResponse();
        $response->status = 200;
        $response->headers = ['Content-Type' => 'text/plain'];
        $response->body = 'Hello from Folk!';
        return $response;
    }
}

4. Build and run:

folk-builder build
./my-folk serve
curl http://localhost:8080/
# Hello from Folk!

With Laravel

No manual handler setup needed — folk-laravel registers LaravelHttpHandler automatically. All your Laravel routes, middleware, and controllers work out of the box:

// routes/web.php — works as-is
Route::get('/ping', fn () => response()->json(['status' => 'ok']));
Route::get('/user/{name}', fn (string $name) => response()->json(['hello' => $name]));

State is reset between requests (auth, DB transactions, events, queue) via built-in resetters.

For latency-sensitive workloads, use runtime = "fork" in [server] to skip framework bootstrap per worker.

Configuration

[http]
listen = "0.0.0.0:8080"
read_timeout = "10s"
write_timeout = "30s"

Key	Type	Default	Description
listen	SocketAddr	"0.0.0.0:8080"	Address and port to bind.
read_timeout	Duration	"10s"	Maximum time to read the request body.
write_timeout	Duration	"30s"	Maximum time to write the response.

Duration format: "10s", "5m", "1h", "500ms".

How it works

The plugin starts a hyper HTTP/1.1 server on the configured address. For each incoming request:

1. Encode — The request (method, URI, headers, body) is serialized to MessagePack as an HttpRequestPayload.
2. Dispatch — The payload is sent to a PHP worker via executor.execute().
3. Decode — The worker returns a MessagePack-encoded HttpResponsePayload (status, headers, body), which is converted back to an HTTP response.

Error responses:

• Encode failure → 500
• Worker error → 502
• Decode failure → 500

The plugin exposes one RPC method, http.connections, which reports the current active connection count via the admin socket.

PHP-side handler registration happens through folk-sdk's WorkerLoop::registerHttpHandler(), which binds to the http.handle RPC method automatically.

License

MIT