Plack-Handler-H2
view release on metacpan or search on metacpan
```
**CentOS/RHEL:**
```bash
sudo yum install nghttp2-devel libevent-devel openssl-devel gcc-c++ make
```
**macOS:**
```bash
brew install nghttp2 libevent openssl
```
### Build and Install the Module
From CPAN (when available):
```bash
cpanm Plack::Handler::H2
```
From source:
```bash
perl Makefile.PL
make
make test
make install
```
## Usage
### Basic Example
Create a PSGI application file (`app.psgi`):
```perl
my $app = sub {
my $env = shift;
return [
200,
['Content-Type' => 'text/plain'],
['Hello, HTTP/2 World!']
];
};
```
Run with plackup:
```bash
# With custom certificates
plackup -s H2 \
--ssl-cert-file=/path/to/server.crt \
--ssl-key-file=/path/to/server.key \
--port=8443 \
app.psgi
# Development mode (auto-generates self-signed certificate)
plackup -s H2 --port=8443 app.psgi
```
### Streaming Response Example
Create a streaming PSGI application (`streaming.psgi`):
```perl
my $app = sub {
my $env = shift;
return sub {
my $responder = shift;
# Send headers and get writer
my $writer = $responder->([
200,
['Content-Type' => 'text/html']
]);
# Stream data in chunks
$writer->write("<html><body>");
$writer->write("<h1>Streaming Response</h1>");
sleep 1; # Simulate processing
$writer->write("<p>This data arrives progressively.</p>");
$writer->write("</body></html>");
# Close the stream
$writer->close();
};
};
```
Run with plackup:
```bash
plackup -s H2 --port=8443 streaming.psgi
```
### Configuration Options
When using plackup, you can pass options via command-line flags:
- **--ssl-cert-file** (optional): Path to SSL certificate file (PEM format)
- If not provided, generates self-signed certificate automatically
- **--ssl-key-file** (optional): Path to SSL private key file (PEM format)
- Required if --ssl-cert-file is provided
- **--host** (optional): IP address to bind to (default: `0.0.0.0`)
- **--port** (optional): Port number to listen on (default: `5000`)
- **--timeout** (optional): General timeout in seconds (default: `120`)
- **--read-timeout** (optional): Read timeout in seconds (default: `60`)
- **--write-timeout** (optional): Write timeout in seconds (default: `60`)
- **--request-timeout** (optional): Request timeout in seconds (default: `30`)
- **--max-request-body-size** (optional): Maximum request body size in bytes (default: `10485760` = 10MB)
Example with custom configuration:
```bash
plackup -s H2 \
--host=127.0.0.1 \
--port=8443 \
--ssl-cert-file=server.crt \
--ssl-key-file=server.key \
--max-request-body-size=20971520 \
app.psgi
```
**Note**: For programmatic use cases where plackup is not suitable, you can instantiate the handler directly with `Plack::Handler::H2->new()`, but this is only recommended for advanced use cases.
## Architecture
The module consists of three main layers:
1. **H2.pm**: High-level Perl interface
- PSGI handler implementation
- Configuration management
- Self-signed certificate generation
- Streaming response coordination
2. **H2.xs**: XS bindings layer
- Efficient Perl-to-C++ interface
- Type conversion and marshalling
- Function wrappers for core operations
3. **plack_handler_h2.cc/h**: Core C++ implementation
- nghttp2 integration for HTTP/2 protocol
- libevent event loop for async I/O
- OpenSSL for TLS/SSL and ALPN
- Request/response handling
- Stream multiplexing
- Memory-efficient body handling (auto-switches to temp files for large bodies)
## Examples
The `example/` directory contains several working examples:
- **example.pl**: Basic PSGI app with form handling
( run in 0.608 second using v1.01-cache-2.11-cpan-f4a522933cf )