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 = { git = "https://github.com/Folk-Project/folk-plugin-http" }
# Once published: 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"
git = "https://github.com/Folk-Project/folk-plugin-http"
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!

For latency-sensitive workloads, use runtime = "fork" in [server] after installing folk-runtime-fork.

Configuration

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