server-agent

README

server-agent

Proxy server agent that optimizes server-side interface performance. Built with connect-rpc over HTTP/3 (QUIC).

Features

• HTTP/3 QUIC transport with TLS
• connect-rpc protocol (compatible with gRPC, gRPC-Web, and Connect protocols)
• Traffic aggregation with buffered batch submission
• User data caching with configurable TTL
• Graceful shutdown with signal handling

RPC Services

Method	Description
Config	Fetch node configuration
Register	Register a node
Unregister	Unregister a node
Heartbeat	Node heartbeat
Submit	Submit user traffic data (aggregated)
Users	Get cached user list
Verify	Verify node registration

Quick Start

# Generate self-signed TLS certificate for development
make cert

# Build
make build

# Run
./bin/server-agent \
  --api https://your-api-host \
  --token your-token \
  --cert_file .cert/server.crt \
  --key_file .cert/server.key

TLS Certificate

make cert generates a CA and server certificate with the following X.509 extensions:

Extension	Value	Description
subjectAltName	DNS:localhost, IP:127.0.0.1	Specifies the hostnames and IPs the certificate is valid for. Modern TLS clients (including Go) require SAN and ignore the CN field.
extendedKeyUsage	serverAuth	Declares the certificate is intended for TLS server authentication. Go's crypto/tls rejects certificates without this extension during handshake.
basicConstraints	CA:FALSE	Marks the certificate as an end-entity certificate, not a CA. Prevents it from being used to sign other certificates.

To customise the certificate, override these variables:

make cert CERT_DIR=.cert CERT_DAYS=365 CERT_CN=localhost

Configuration

All flags support environment variables:

Flag	Env	Default	Description
--server_host	SERVER_HOST	0.0.0.0	Listen address
--port	SERVER_PORT	8443	Listen port
--cert_file	CERT_FILE	/root/.cert/server.crt	TLS certificate
--key_file	KEY_FILE	/root/.cert/server.key	TLS private key
--api	API	(required)	Backend API address
--token	TOKEN	(required)	API token
--timeout	TIMEOUT	15s	API timeout
--log_mode	LOG_MODE	error	Log level: debug, info, error
--data_dir	DATA_DIR	/var/lib/server-agent	Data directory
--agg_submit_interval	AGG_SUBMIT_INTERVAL	5m	Traffic aggregation submit interval
--agg_submit_buffer_size	AGG_SUBMIT_BUFFFER_SIZE	-	Submission buffer pool size
--agg_submit_worker_num	AGG_SUBMIT_WORKER_NUM	-	Submission worker count
--cache_user_ttl	CACHE_USER_TTL	-	User cache TTL

Make Targets

Target	Description
make build	Build binary to bin/server-agent
make cert	Generate self-signed TLS certificate in .cert/
make fmt	Format code
make lint	Run linter
make test	Run tests