folk-plugin-http 0.1.1

# folk-plugin-http

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

> **Status:** in active development. See [folk-spec](https://github.com/Folk-Project/folk-spec) for the roadmap.

## Requirements

- Rust 1.85+
- [folk-api](https://github.com/Folk-Project/folk-api) (only dependency for plugin compilation)

## Installation

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

## Quick start

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

```toml
[build]
output = "my-folk"

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

2. Configure in `folk.toml`:

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

3. Write a PHP handler:

```php
<?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:

```bash
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

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

## 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](https://github.com/Folk-Project/folk-sdk)'s `WorkerLoop::registerHttpHandler()`, which binds to the `http.handle` RPC method automatically.

## License

MIT