pingora
stableHigh-performance HTTP reverse proxy and load balancer built on Cloudflare's Pingora framework, exposing server lifecycle, proxy hook registration, and upstream peer configuration.
use plugin pingora::{Note: this plugin is not supported on Windows. On Windows every function returns an error. Use WSL2, Linux, or macOS., Pingora.server, PingoraServer.run_forever, …} Functions (13)
- Note: this plugin is not supported on Windows. On Windows every function returns an error. Use WSL2, Linux, or macOS.
- Pingora.server Create a Pingora server instance
- PingoraServer.run_forever Start the server and block forever
- Pingora.proxy Create an HTTP proxy wired to a server
- PingoraProxy.add_tcp Add a TCP listen address to a proxy
- PingoraProxy.finalize Bake the proxy service into the server
- Pingora.peer Create an upstream HTTP peer
- PingoraPeer.set_tls Enable or disable TLS for a peer
- PingoraPeer.set_sni Set the TLS SNI hostname
- PingoraPeer.set_connect_timeout Set connection timeout in ms
- PingoraPeer.set_read_timeout Set read timeout in ms
- PingoraPeer.set_write_timeout Set write timeout in ms
- PingoraPeer.set_verify_cert Enable or disable TLS cert verification
Create a Pingora server instance
Creates and bootstraps a Pingora server. config is an optional table; pass #{"threads": 8} to control the worker-thread count (default 4). Returns a handle that proxy services are registered against before calling run_forever.
use plugin pingora::{Pingora}
let srv = Pingora.server(#{"threads": 4})
// add proxies, then:
// srv.run_forever()
Start the server and block forever
Starts the server event loop, adds all registered proxy services, and blocks indefinitely. This call never returns under normal operation — the process exits on shutdown signal.
use plugin pingora::{Pingora}
let srv = Pingora.server(#{"threads": 4})
let proxy = Pingora.proxy(srv, #{"upstream_peer": fn(session, ctx) {
return Pingora.peer("127.0.0.1:8080")
}})
proxy.add_tcp("0.0.0.0:8000")
srv.run_forever()
Create an HTTP proxy wired to a server
Creates an HTTP proxy service attached to server. hooks is a table mapping hook names to handler functions. The required hook is upstream_peer; optional hooks include request_filter, response_filter, upstream_request_filter, and logging.
use plugin pingora::{Pingora}
let srv = Pingora.server(#{})
let proxy = Pingora.proxy(srv, #{
"upstream_peer": fn(session, ctx) {
return Pingora.peer("10.0.0.1:9000")
},
"request_filter": fn(session, ctx) {
return false
}
})
proxy.add_tcp("0.0.0.0:3000")
srv.run_forever()
Add a TCP listen address to a proxy
Registers a TCP listen address (e.g. "0.0.0.0:8080") on the proxy. Call before run_forever or finalize. Multiple addresses can be added.
use plugin pingora::{Pingora}
let srv = Pingora.server(#{})
let proxy = Pingora.proxy(srv, #{
"upstream_peer": fn(session, ctx) {
return Pingora.peer("127.0.0.1:9000")
}
})
proxy.add_tcp("0.0.0.0:80")
proxy.add_tcp("0.0.0.0:8080")
srv.run_forever()
Bake the proxy service into the server
Explicitly bakes the proxy's service into the server before run_forever. Calling this is optional — run_forever auto-finalizes all pending proxies. Use it if you need to finalize proxies in a specific order.
use plugin pingora::{Pingora}
let srv = Pingora.server(#{})
let proxy = Pingora.proxy(srv, #{
"upstream_peer": fn(session, ctx) {
return Pingora.peer("127.0.0.1:9000")
}
})
proxy.add_tcp("0.0.0.0:8080")
proxy.finalize()
srv.run_forever()
Create an upstream HTTP peer
Creates an upstream peer pointing to addr (e.g. "backend.internal:443"). The peer handle is returned from the upstream_peer hook to tell Pingora where to forward the request.
use plugin pingora::{Pingora}
let srv = Pingora.server(#{})
Pingora.proxy(srv, #{
"upstream_peer": fn(session, ctx) {
let peer = Pingora.peer("api.example.com:443")
peer.set_tls(true)
peer.set_sni("api.example.com")
return peer
}
})
Enable or disable TLS for a peer
Enables (true) or disables (false) TLS for connections to this upstream peer.
use plugin pingora::{Pingora}
let peer = Pingora.peer("secure.example.com:443")
peer.set_tls(true)
Set the TLS SNI hostname
Sets the TLS Server Name Indication hostname. Must be set when set_tls(true) is used and the upstream requires SNI.
use plugin pingora::{Pingora}
let peer = Pingora.peer("10.0.0.5:443")
peer.set_tls(true)
peer.set_sni("api.internal.example.com")
Set connection timeout in ms
Sets the TCP connection timeout in milliseconds for this upstream peer.
use plugin pingora::{Pingora}
let peer = Pingora.peer("slow-backend:8080")
peer.set_connect_timeout(2000)
Set read timeout in ms
Sets the read timeout in milliseconds. If the upstream does not send data within this window, the connection is dropped.
use plugin pingora::{Pingora}
let peer = Pingora.peer("backend:8080")
peer.set_read_timeout(5000)
Set write timeout in ms
Sets the write timeout in milliseconds for sending the upstream request.
use plugin pingora::{Pingora}
let peer = Pingora.peer("backend:8080")
peer.set_write_timeout(3000)
Enable or disable TLS cert verification
Enables or disables TLS certificate verification for this peer. Set to false for self-signed certificates in development environments.
use plugin pingora::{Pingora}
let peer = Pingora.peer("dev-backend:8443")
peer.set_tls(true)
peer.set_verify_cert(false)