folk-plugin-http 0.1.0

HTTP plugin for Folk — accepts connections via hyper and dispatches to PHP workers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# 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 = { 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`:

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

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