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 Plugin snippets can be edited in the Playground, but native capabilities are executed locally with the Zolo CLI.
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
From import to result
- 01Import only what you use
- 02Copy the smallest example
- 03Run it with the Zolo CLI
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": |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": |session, ctx| {
return Pingora.peer("10.0.0.1:9000")
},
"request_filter": |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": |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": |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": |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)