architecture
a look at how funnel works under the hood.
funnel's architecture is designed to be both simple and efficient, relying on a persistent websocket connection to proxy http requests. the system consists of two main components: the funnel server and the funnel client.
system diagram
this diagram illustrates the flow of a request from an end-user to your local application.
component breakdown
communication protocol
websocket is key
the entire system is built around the websocket protocol. this allows for a persistent, bi-directional communication channel between the client and server, which is more efficient than traditional http polling for this use case.
connection: the client initiates a websocket connection to the server's /ws endpoint, providing its desired tunnel id in the query parameters (/ws?id=my-tunnel).
registration: the server validates the id. if it's available, it creates a new tunnel instance and associates it with the websocket connection.
request proxying:
- an http request arrives at
my-tunnel.server.com. - the server's router extracts the subdomain (
my-tunnel), finds the active tunnel, and constructs a json message containing the request details (method, path, headers, body). - this message is sent down the websocket to the client.
local forwarding:
- the client receives the message, reconstructs the http request, and forwards it to the local service.
response proxying:
- the local service returns a response.
- the client captures this response, serializes it into a json message, and sends it back to the server.
final response:
- the server receives the response message and writes its contents (status code, headers, body) back to the original http requester.