getting-started.md

Getting Started

Install

go get github.com/777genius/proxykit@v0.1.7

If proxy.golang.org is still catching up to a fresh release, prefer the explicit tagged version shown here instead of @latest.

proxykit is a library-first project. You embed handlers inside your application instead of running a prebuilt control plane.

First reverse proxy

This is the smallest useful mounted reverse proxy:

package main

import (
  "log"
  "net/http"

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

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

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

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

Request flow:

GET /proxy/api/users?_target=https://example.com
-> upstream target https://example.com/api/users

Add observation hooks

You can attach session, HTTP, and WebSocket observation without coupling to a storage engine:

handler, err := reverseproxy.New(reverseproxy.Options{
  Resolver: reverseproxy.QueryTargetResolver{MountPath: "/proxy"},
  Hooks: observe.Hooks{
    OnSessionOpen: func(_ context.Context, s observe.Session) error {
      log.Printf("open %s %s", s.Kind, s.Target)
      return nil
    },
    OnHTTPRoundTrip: func(_ context.Context, rt observe.HTTPRoundTrip) error {
      log.Printf("%s -> %d", rt.Request.URL, rt.Response.StatusCode)
      return nil
    },
  },
})

Recommended adoption path

If you are introducing proxykit into an existing application, this order usually keeps risk down:

1. Start with one transport package such as reverse or wsproxy.
2. Keep your existing routes and DTOs in your own app layer.
3. Move capture, persistence, and delivery logic behind observation hooks.
4. Add forward, connect, cookies, or proxyruntime only when the product really needs them.

Where to go next

• Architecture for what belongs inside proxykit
• Packages for the package map
• Observation Hooks for the main extension surface
• Comparisons for how this differs from goproxy, oxy, and martian