github.com/go-gost/core defines all interfaces and shared types for the GOST tunneling toolkit. It has no implementations and zero third-party dependencies — just Go's standard library. All concrete types live in the x/ module.
The module defines every component of the GOST proxy pipeline:
- Service — Wraps a listener + handler into a runnable server
- Listener — Accepts inbound connections (TCP, TLS, HTTP/2/3, QUIC, etc.)
- Handler — Processes inbound connections: authenticates, routes, forwards
- Dialer — Dials from one node to the next proxy hop
- Connector — Connects from the final node to the destination
- Chain / Route / Transporter / Node / Hop — Proxy chain routing and node selection
- Router — Top-level router combining chain, resolver, host mapping, retries, and timeouts
- Registry[T] — Generic typed registry for component registration
- Selector / Strategy / Filter — Generic load balancing and node selection
Supporting types: Authenticator, Admission, Bypass, Resolver, HostMapper, Recorder, Observer, Ingress, SD (service discovery), Logger, Metrics, Limiter (conn/rate/traffic), Stats, Matcher, and Router (OS-level).
Client
│
▼
┌──────────────┐
│ Listener │ Accepts inbound connections
│ │ (tcp, tls, ws, http2/3, quic, kcp, icmp, tun, udp, ...)
└──────┬───────┘
│ net.Conn
▼
┌──────────────┐
│ Handler │ Authenticates, routes, and proxies traffic
│ │ (http, socks4/5, ss, ssh, tunnel, tun, dns, redirect, ...)
└──────┬───────┘
│ chain.Router.Dial(ctx, network, address)
▼
┌──────────────────────────────────────────────────────────────┐
│ chain.Router │
│ │
│ Resolver ─► HostMapper ─► Recorders ─► Retries/Timeout │
│ │ │
│ ▼ │
│ ┌─────────┐ ┌─────┐ ┌──────────┐ │
│ │ Chainer │──►│ Hop │──►│ Node[] │ (per chain hop) │
│ └─────────┘ └──┬──┘ └────┬─────┘ │
│ │ │ │
│ Selector chain.Transporter │
│ (rr/random/ ┌──────────────────┐ │
│ weighted/ │ Dialer │ dial to next │
│ fail-filter) │ Handshaker │ proxy hop │
│ │ Connector │ connect to │
│ │ Binder │ destination │
│ │ Multiplexer │ │
│ └──────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
▼
Destination
Client ◄── Tunnel ──┐
│
┌─────▼──────┐
│ Listener │
└─────┬──────┘
│
┌─────▼──────┐
│ Handler │
└─────┬──────┘
│ chain.Router.Bind(ctx, network, address)
▼
chain.Router ─► chain.Route.Bind() ─► Transporter.Bind()
│ │
▼ ▼
Destination net.Listener (on remote node)
┌────────────────────────────────────────┐
│ Service │
│ │
│ ┌──────────┐ ┌───────────┐ │
│ │ Listener │─────────►│ Handler │ │
│ │ │ net.Conn │ │ │
│ └──────────┘ └─────┬─────┘ │
│ │ │
│ chain.Router │
└────────────────────────────────────────┘
Service = 1 Listener + 1 Handler + cross-cutting concerns:
Listener.Options: Handler.Options:
Auth Auth / Auther
Auther Bypass
Admission Router
ConnLimiter RateLimiter
TrafficLimiter TrafficLimiter
Stats TLSConfig
ProxyProtocol Observer
Router (chain.Router) Recorders
Logger Logger
┌──────────┐
│ Registry │ Generic[T]: Register / Get / GetAll
└──────────┘
│
│ registers
▼
┌─────────┐ ┌───────────┐ ┌────────────┐
│ Service │────►│ Listener │ │ Handler │
└─────────┘ └─────┬─────┘ └──────┬─────┘
│ │
│ chain.Router │
└────────┬─────────┘
│
┌────────────┴────────────┐
│ chain.Router │
│ .Chainer │
│ .Resolver │
│ .HostMapper │
│ .Recorders │
└────────────┬────────────┘
│
┌────────────┴───────────┐
│ chain.Chainer │
│ Route(ctx, ...) │
└────────────┬───────────┘
│
┌────────────┴───────────┐
│ chain.Route │
│ Dial() / Bind() │
│ Nodes() │
└────────────┬───────────┘
│
┌────────────┴───────────┐
│ hop.Hop │
│ Select(ctx, opts) │
│ uses selector.Selector│
└────────────┬───────────┘
│
┌────────────┴───────────┐
│ chain.Node │
│ .Transport │
│ .Bypass │
│ .Resolver / .HostMapper│
│ .TLS / .HTTP settings │
│ .Marker (fail count) │
└────────────┬───────────┘
│
┌────────────┴───────────┐
│ chain.Transporter │
│ ┌──────────────────┐ │
│ │ dialer.Dialer │ │
│ │ connector.Con.. │ │
│ │ Handshaker │ │
│ │ Multiplexer │ │
│ │ Binder │ │
│ └──────────────────┘ │
└────────────────────────┘
┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────────┐
│ Auth │ │ Admission│ │ Bypass │ │ Recorder │ │ Observer │
├──────────┤ ├──────────┤ ├───────────┤ ├──────────┤ ├──────────────┤
│Authen... │ │Admit() │ │Contains() │ │Record() │ │Observe() │
│(user,pw) │ │(addr) │ │IsWhite... │ │(bytes) │ │(events) │
└──────────┘ └──────────┘ └───────────┘ └──────────┘ └──────────────┘
┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────────┐
│ Resolver │ │HostMapper│ │ Logger │ │ Metrics │ │ Router │
├──────────┤ ├──────────┤ ├───────────┤ ├──────────┤ ├──────────────┤
│Resolve() │ │Lookup() │ │Tracef() │ │Counter() │ │GetRoute() │
│(host→IP) │ │(host→IP) │ │Debugf() │ │Gauge() │ │(dst→gateway) │
│ │ │ │ │Infof()... │ │Observer()│ │ │
└──────────┘ └──────────┘ └───────────┘ └──────────┘ └──────────────┘
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ conn.Limiter │ │ rate.Limiter │ │ traffic.Limiter │
├──────────────────┤ ├──────────────────┤ ├──────────────────┤
│ Allow(n) bool │ │ Allow(n) bool │ │ Wait(ctx,n) int │
│ Limit() int │ │ Limit() float64 │ │ Limit() / Set() │
│ (max conn count) │ │ (rate limiter) │ │ (bandwidth) │
└──────────────────┘ └──────────────────┘ └──────────────────┘
┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────────┐
│ SD │ │ Ingress │ │ Matcher │ │ Stats │ │ BufPool │
├──────────┤ ├──────────┤ ├───────────┤ ├──────────┤ ├──────────────┤
│Register()│ │SetRule() │ │Match() │ │Add/Get() │ │Get() / Put() │
│Get() │ │GetRule() │ │(*Request) │ │conn/bytes│ │(tiered sync. │
│ │ │ │ │ │ │ │ │ Pool) │
└──────────┘ └──────────┘ └───────────┘ └──────────┘ └──────────────┘
import (
"github.com/go-gost/core/chain"
"github.com/go-gost/core/connector"
"github.com/go-gost/core/dialer"
"github.com/go-gost/core/handler"
"github.com/go-gost/core/listener"
"github.com/go-gost/core/registry"
"github.com/go-gost/core/service"
)All interfaces follow the functional options pattern. See x/ for implementations.