README.md

GOST Plugin SDK

gRPC-based plugin protocol definitions for GOST. This module defines the service contracts that external plugin processes implement to extend GOST with custom authentication, admission control, traffic limiting, DNS resolution, and more.

Available plugins

Plugin	Service	Description
admission	Admission	Allow/deny connections by address
auth	Authenticator	Authenticate users and clients
bypass	Bypass	Bypass the proxy chain for specific hosts
hop	Hop	Custom node selection for proxy chains
hosts	HostMapper	Static or dynamic host-to-IP mapping
ingress	Ingress	Ingress rule management
limiter/traffic	Limiter	Per-connection bandwidth limits
observer	Observer	Receive connection and traffic events
recorder	Recorder	Record proxied traffic
resolver	Resolver	Custom DNS resolution
router	Router	Custom route selection
sd	SD	Service discovery (register/deregister/get)

Usage

gRPC plugin server

package main

import (
    "context"
    "flag"
    "fmt"
    "log"
    "net"

    "github.com/go-gost/plugin/admission/proto"
    "google.golang.org/grpc"
)

var port = flag.Int("port", 8000, "Server port")

type server struct {
    proto.UnimplementedAdmissionServer
}

func (s *server) Admit(ctx context.Context, req *proto.AdmissionRequest) (*proto.AdmissionReply, error) {
    reply := &proto.AdmissionReply{}
    if req.GetAddr() == "127.0.0.1:80" {
        reply.Ok = true
    }
    return reply, nil
}

func main() {
    flag.Parse()
    lis, _ := net.Listen("tcp", fmt.Sprintf(":%d", *port))
    s := grpc.NewServer()
    proto.RegisterAdmissionServer(s, &server{})
    log.Fatal(s.Serve(lis))
}

HTTP plugin server

GOST also supports HTTP/JSON transport. The endpoint path matches the plugin type:

package main

import (
    "encoding/json"
    "flag"
    "fmt"
    "log"
    "net"
    "net/http"
)

var port = flag.Int("port", 8000, "Server port")

func main() {
    flag.Parse()
    lis, _ := net.Listen("tcp", fmt.Sprintf(":%d", *port))
    http.HandleFunc("/admission", func(w http.ResponseWriter, r *http.Request) {
        var req struct {
            Addr    string `json:"addr"`
            Service string `json:"service"`
        }
        json.NewDecoder(r.Body).Decode(&req)
        json.NewEncoder(w).Encode(map[string]bool{"ok": req.Addr == "127.0.0.1:80"})
    })
    log.Fatal(http.Serve(lis, nil))
}

Configuration

Point GOST at your plugin server via the plugin block in config:

services:
  - name: service-0
    addr: ":8080"
    handler:
      type: http
    listener:
      type: tcp
    plugin:
      type: admission
      addr: 127.0.0.1:8000

Code generation

Generated protobuf code was produced with protoc-gen-go v1.28.1 and protoc-gen-go-grpc v1.2.0. To regenerate:

protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    admission.proto

License

MIT