proxykit

module
v0.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2026 License: Apache-2.0

README

proxykit

Go Reference Release CI Docs Docs Site Discussions

proxykit is a standalone Go proxy foundation for applications that need:

  • reverse HTTP proxying
  • forward HTTP proxying
  • CONNECT tunneling
  • WebSocket proxying
  • listener lifecycle management
  • neutral transport observation hooks

It is intentionally not a product backend, API server, or gateway control plane.

Why not goproxy, oxy, or Martian?

Those projects are real and useful, but they optimize for different shapes:

  • goproxy is a mature programmable HTTP/HTTPS proxy with a more monolithic center
  • oxy is strongest as an HTTP reverse-proxy and middleware toolkit
  • Martian is excellent when you want a deeper modifier-driven HTTP testing proxy

Choose proxykit when your application needs one embeddable foundation for reverse + forward + CONNECT + WebSocket, while keeping routes, storage, admin APIs, and UI-facing contracts in your own adapter layer.

Capability map

Need Package
mounted reverse proxy route reverse
absolute-URI forward proxy forward
plain CONNECT tunneling connect
WebSocket proxying wsproxy
transport-neutral hooks observe
forward and SOCKS listener lifecycle proxyruntime
cookie rewriting helpers cookies
focused transport helpers proxyhttp, socketio, mitm

Quick start

package main

import (
	"log"
	"net/http"

	"github.com/777genius/proxykit/reverse"
)

func main() {
	handler, err := reverse.New(reverse.Options{
		Resolver: reverse.QueryTargetResolver{
			MountPath:     "/proxy",
			DefaultTarget: "https://example.com",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	mux := http.NewServeMux()
	mux.Handle("/proxy", handler)
	mux.Handle("/proxy/", handler)

	log.Fatal(http.ListenAndServe(":8080", mux))
}

Documentation

Main docs sections:

Quick package map

  • reverse - mounted reverse HTTP proxy handler
  • forward - absolute-URI HTTP forward proxy handler
  • connect - plain CONNECT tunnel handler
  • wsproxy - WebSocket proxy handler
  • proxyruntime - forward and SOCKS listener lifecycle
  • observe - transport-neutral hooks and event structs
  • cookies, proxyhttp, socketio, mitm - focused supporting packages

Real-world example

proxykit already powers a production-style application:

  • flutter_network_debugger - a Flutter + Go network debugging app built on top of proxykit through an application adapter layer

This repo is the reusable transport foundation extracted from that application, not a copy of the whole product backend.

flowchart LR
    A["proxykit core"] --> B["app adapters"]
    B --> C["flutter_network_debugger"]

Design rules

  • no UI-specific contracts in public packages
  • small packages with explicit boundaries
  • application routes, persistence, and delivery protocols stay outside the module
  • transport packages expose hooks instead of owning storage or REST DTOs

Install

go get github.com/777genius/proxykit@latest

Why this repo is intentionally smaller than a full backend

proxykit is the reusable transport foundation, not a full proxy product backend.

That means the public module intentionally excludes:

  • app-specific REST routes
  • monitor room protocols
  • storage ownership
  • UI DTOs and preview payloads
  • admin auth and settings APIs

Build the docs locally

The docs site uses the latest VitePress alpha line from npm.

npm install
npm run docs:dev

Verification

go vet ./...
go test ./...
go test -race ./...
npm run docs:build

Contributing

See CONTRIBUTING.md for workflow, architecture guardrails, and review expectations.

For community processes:

Directories

Path Synopsis
Package connect provides an HTTP CONNECT tunneling handler.
 Package connect provides an HTTP CONNECT tunneling handler.
Package cookies provides proxy-safe cookie rewriting helpers for mounted reverse proxies.
 Package cookies provides proxy-safe cookie rewriting helpers for mounted reverse proxies.
examples
forward-connect command
reverse-basic command
ws-observe command
Package forward provides a reusable HTTP forward proxy handler for absolute URI requests.
 Package forward provides a reusable HTTP forward proxy handler for absolute URI requests.
internal
httpcapture
Package mitm provides optional TLS interception primitives for proxykit.
 Package mitm provides optional TLS interception primitives for proxykit.
Package observe defines transport-neutral observation contracts shared by proxykit packages.
 Package observe defines transport-neutral observation contracts shared by proxykit packages.
Package proxyhttp provides shared HTTP proxy transport primitives.
 Package proxyhttp provides shared HTTP proxy transport primitives.
Package proxyruntime manages long-lived proxy listeners such as HTTP forward-proxy and SOCKS5 endpoints.
 Package proxyruntime manages long-lived proxy listeners such as HTTP forward-proxy and SOCKS5 endpoints.
Package reverse provides a reusable HTTP reverse proxy handler with transport-level mutation and observation hooks.
 Package reverse provides a reusable HTTP reverse proxy handler with transport-level mutation and observation hooks.
Package socketio parses Socket.IO event-style packets from text frames.
 Package socketio parses Socket.IO event-style packets from text frames.
Package wsproxy provides a reusable WebSocket proxy handler with hook-based observation points and target resolution abstractions.
 Package wsproxy provides a reusable WebSocket proxy handler with hook-based observation points and target resolution abstractions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.