amz

README

AMZ - Third-Party Cloudflare WARP SDK

中文

This is a Go SDK that allows you to embed the Cloudflare WARP proxy directly into your application.

You only need to integrate it via amz.NewClient(...); the SDK will automatically handle registration, state persistence, endpoint selection, and runtime initialization.

Features

• Post-quantum encryption with X25519MLKEM768
• HTTP, SOCKS5 proxies
• L4 transport layer proxy
• Proxy port reuse
• Automatic registration
• Automatic endpoint selection

Use Cases

Ideal for applications that only need to change their external IP via Cloudflare WARP without additional features, and want to avoid the official ~100MB client.

I use this for my network probe, which is deployed on an ultra-small VPS with 1 CPU core, 1GB RAM, and 10GB SSD.

Why Choose AMZ

There are several WARP libraries based on WireGuard in the community—why choose AMZ?

• High Performance: In internal Cloudflare tests, the QUIC L4 proxy achieves double the download and upload speeds compared to WireGuard, with significantly reduced latency.
• Small Size: ~1.1MB compiled binary with full implementation of the latest WARP proxy model
• Multi-Channel: Built-in HTTP, SOCKS5 proxy channels with excellent extensibility for adding more protocols
• Enhanced Security: Modern hybrid key exchange using X25519 + ML-KEM-768 for quantum-resistant encryption

Roadmap

• TUN
• Team WARP
• More complex optimization strategies
• Connection Performance Optimization
• Improve log slicing
• Improve observability

Quick Start

go get github.com/skye-z/amz

Below is an example enabling both HTTP and SOCKS5 proxy channels:

package main

import (
	"context"
	"log"

	"github.com/skye-z/amz"
)

func main() {
	client, err := amz.NewClient(amz.Options{
		Storage: amz.StorageOptions{
			Path: "./amz.state.json",
		},
		Listen: amz.ListenOptions{
			Address: "127.0.0.1:9811",
		},
		HTTP: amz.HTTPOptions{
			Enabled: true,
		},
		SOCKS5: amz.SOCKS5Options{
			Enabled: true,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	if err := client.Start(context.Background()); err != nil {
		log.Fatal(err)
	}

	log.Printf("proxy listening on %s", client.ListenAddress())
}

For a blocking implementation, simply call Run():

client, err := amz.NewClient(opts)
if err != nil {
	panic(err)
}
defer client.Close()

if err := client.Run(); err != nil {
	panic(err)
}

Documentation

Index

• Variables
• type Client
  • func NewClient(opts Options) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) ListenAddress() string
  • func (c *Client) Run() error
  • func (c *Client) Start(ctx context.Context) error
  • func (c *Client) Status() Status
• type HTTPOptions
• type ListenOptions
• type Logger
• type Options
• type SOCKS5Options
• type Status
• type StorageOptions
• type TUNOptions
• type TransportOptions

Variables

var (
	ErrNoRuntimeEnabled = errors.New("at least one runtime must be enabled")
	ErrClientClosed     = errors.New("client already closed")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(opts Options) (*Client, error)

func (*Client) Close

func (c *Client) Close() error

func (*Client) ListenAddress

func (c *Client) ListenAddress() string

func (*Client) Run

func (c *Client) Run() error

func (*Client) Start

func (c *Client) Start(ctx context.Context) error

func (*Client) Status

func (c *Client) Status() Status

type HTTPOptions

type HTTPOptions struct {
	Enabled bool
}

type ListenOptions

type ListenOptions struct {
	Address string
}

type Logger

type Logger interface {
	Printf(format string, args ...any)
}

Logger is the minimal public logging contract for amz. It is compatible with standard log.Logger and the internal runtime logger.

type Options

type Options struct {
	Storage   StorageOptions
	Listen    ListenOptions
	Transport TransportOptions
	HTTP      HTTPOptions
	SOCKS5    SOCKS5Options
	TUN       TUNOptions
	Logger    Logger
}

type SOCKS5Options

type SOCKS5Options struct {
	Enabled bool
}

type Status

type Status struct {
	Running       bool
	ListenAddress string
	Endpoint      string

	HTTPEnabled   bool
	SOCKS5Enabled bool
	TUNEnabled    bool

	Registered bool
}

type StorageOptions

type StorageOptions struct {
	Path string
}

type TUNOptions

type TUNOptions struct {
	Enabled bool
}

type TransportOptions

type TransportOptions struct {
	Endpoint string
	SNI      string
}