README
¶
chrome
Services implemented in Go.
Install
# go install github.com/b97tsk/chrome/cmd/chrome@latest
Usage
Create a config file (see below), then run:
chrome path/to/your/config/file
If config file is not specified, chrome.yaml is assumed.
If config file is -, chrome will try to load config from standard input.
Sample Config File
log:
file: chrome.log # Write log messages to this file.
level: INFO # Log level, alternatives are ERROR, WARN, DEBUG, TRACE and NONE.
conn:
timeout: 10s # Default connect timeout.
alias#1: # Field names start with word `alias` are ignored.
- &SS ss://method:[email protected]:12345
- &Tor socks5://127.0.0.1:9150
# Create three TCP tunnels over different forward proxies.
tcptun#1: # Note that field names must be unique.
on: 127.1.2.7:53 # Listen address.
for: 1.1.1.1:53 # Forward target.
over: Direct # Direct access, which is the default.
tcptun#2: # The first word is the service name, which must be valid.
on: 127.1.2.7:5353
for: 8.8.8.8:53
over: *SS
tcptun#3:
on: 127.1.2.7:443
for: www.google.com:443
over: *Tor
# Create three SOCKS5 servers over different forward proxies.
socks#1:
on: 127.1.2.7:1080 # Listen address.
over: Direct # Direct access, which is the default.
socks#2:
on: 127.1.2.7:1081
over: *SS
socks#3:
on: 127.1.2.7:1082
over: *Tor
# Create three Shadowsocks servers over different forward proxies.
shadowsocks#1:
on: :10800 # Listening on all available IP addresses of the local system.
method: aes-256-gcm
password: 123456
over: [] # Direct access, which is the default.
shadowsocks#2:
on: :10801
method: aes-256-gcm
password: 123456
over: [*SS, *Tor] # Chain proxies, one over another.
shadowsocks#3:
on: :10802
method: aes-256-gcm
password: !!binary MTIzNDU2 # Encoded in Base64.
over: [Direct, *SS, Direct] # `Direct`s are simply ignored.
Documentation
¶
Overview ¶
Package chrome is a library that can manage and start various services implemented in Go (currently, very TCP centric).
Index ¶
- Variables
- type Bytes
- type ConnEvent
- type ConnEventMaxAttempts
- type ConnEventResponse
- type ConnOptions
- type Context
- type EnvString
- type Event
- type Job
- type LoadEvent
- type LoadedEvent
- type Manager
- func (m *Manager) AddService(service Service)
- func (m *Manager) CloseConnections()
- func (m *Manager) Load(r io.Reader) error
- func (m *Manager) LoadFS(fsys fs.FS, name string) error
- func (m *Manager) LoadFile(name string) error
- func (m *Manager) LogLevel() log.Level
- func (m *Manager) Logger(name string) *log.Logger
- func (m *Manager) NewConn(remoteAddr string, getRemote func(context.Context) (net.Conn, error), ...) net.Conn
- func (m *Manager) Open(name string) (fs.File, error)
- func (m *Manager) Relay(l, r net.Conn, opts RelayOptions)
- func (m *Manager) Serve(ln net.Listener, fn func(net.Conn))
- func (m *Manager) Service(name string) Service
- func (m *Manager) SetConnOptions(opts ConnOptions)
- func (m *Manager) SetLogFile(name string) error
- func (m *Manager) SetLogLevel(level log.Level)
- func (m *Manager) SetLogOutput(w io.Writer)
- func (m *Manager) SetRelayOptions(opts RelayOptions)
- func (m *Manager) Shutdown()
- func (m *Manager) StartService(ctx context.Context, service Service, name string) (Job, error)
- func (m *Manager) StopJobs()
- type Proxy
- type RelayOptions
- type Service
- type StringList
Constants ¶
This section is empty.
Variables ¶
var CloseConn error = closeConnError{}
Functions ¶
This section is empty.
Types ¶
type Bytes ¶
type Bytes int64
Bytes is a helper type for unmarshaling an int64 from YAML. When unmarshaling, Bytes accepts a binary prefix, for example, 1K = 1024.
type ConnEventMaxAttempts ¶
type ConnEventMaxAttempts struct{}
type ConnEventResponse ¶
type ConnEventResponse struct{}
type ConnOptions ¶
type ConnOptions struct {
// Timeout for each attempt to dial.
Timeout time.Duration
// Interval specifies the minimum interval between two consecutive attempts.
// If one attempt fails shortly, next attempt has to wait.
Interval time.Duration
// Parallel specifies the number of attempts that can be made at the same time.
Parallel int
// MaxAttempts specifies the maximum number of attempts that can be made for each NewConn call.
MaxAttempts int
}
ConnOptions provides options for NewConn.
type Context ¶
type Context struct {
// The Context for cancellation. It is canceled when the job gets canceled.
context.Context
// The name of the job.
JobName string
// The Manager that starts the job.
Manager *Manager
// The channel for receiving events sent to the job.
Event <-chan Event
}
A Context provides contextual values for a job.
type EnvString ¶
type EnvString string
EnvString is a helper type for unmarshaling a string from YAML. When unmarshaling, it calls os.ExpandEnv on the original string and stores the result.
type Job ¶
type Job struct {
// The Context for cancellation. It is canceled when the job stops.
context.Context
// Cancel cancels the job and later cancels Context after Service.Run returns.
Cancel context.CancelFunc
// The channel for sending events to the job.
Event chan<- Event
}
A Job provides mechanism to control the job started by a Service.
type LoadEvent ¶
type LoadEvent struct {
Options any
}
LoadEvent is for sending options to a job.
When a job receives this event, it should only parse the options but not start doing anything what it's supposed to do, not until the job receives a LoadedEvent.
If a job has acquired some system resources (for example, listening to a port) but no longer needs them, this is the good chance to release them, so other jobs can acquire them.
type LoadedEvent ¶
type LoadedEvent struct{}
LoadedEvent is for telling a job to start doing what it's supposed to do.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
A Manager manages services and jobs started by services.
func (*Manager) AddService ¶
AddService registers a Service. Registering services are important for Load(File|FS) methods. Unregistered services cannot be started by Load(File|FS) methods.
func (*Manager) CloseConnections ¶
func (m *Manager) CloseConnections()
CloseConnections closes all connections that Serve accepts.
Shutdown calls CloseConnections.
func (*Manager) NewConn ¶
func (m *Manager) NewConn( remoteAddr string, getRemote func(context.Context) (net.Conn, error), connOpts ConnOptions, relayOpts RelayOptions, logger *log.Logger, lifeCycle func(c <-chan ConnEvent), ) net.Conn
NewConn returns a net.Conn that tries to make a connection to remoteAddr repeatedly until success or the maximum number of attempts has been made.
func (*Manager) Open ¶
Open implements fs.FS. Open is available for jobs started by Load(File|FS) methods when they are handling options.
func (*Manager) Relay ¶
func (m *Manager) Relay(l, r net.Conn, opts RelayOptions)
Relay (TCP only) sends packets from local to remote, and vice versa.
func (*Manager) Serve ¶
Serve accepts incoming connections on the Listener ln and calls fn for each accepted connection in a goroutine. The connection is closed when fn returns.
func (*Manager) Service ¶
Service gets the Service that was registered by AddService. Service returns nil if there is no registered Service with this name. Service returns Dummy if name is not considered a real Service name.
func (*Manager) SetConnOptions ¶
func (m *Manager) SetConnOptions(opts ConnOptions)
SetConnOptions sets default options for NewConn, which may be overrided when NewConn is called.
func (*Manager) SetLogFile ¶
SetLogFile sets the file that each logging message would write to.
func (*Manager) SetLogLevel ¶
SetLogLevel sets the logging level.
func (*Manager) SetLogOutput ¶
SetLogOutput sets a io.Writer that each logging message would write to.
func (*Manager) SetRelayOptions ¶
func (m *Manager) SetRelayOptions(opts RelayOptions)
SetRelayOptions sets default options for Relay, which may be overrided when Relay.
func (*Manager) Shutdown ¶
func (m *Manager) Shutdown()
Shutdown shutdowns and cleanups the Manager.
func (*Manager) StartService ¶
StartService starts a Service. Jobs started by StartService are not managed but they should be stopped manually before you Shutdown the Manager since somehow they are connected to the Manager.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy is a helper type for unmarshaling a proxy from YAML. A Proxy is basically a proxy.Dialer.
func MakeProxy ¶
MakeProxy chains one or more proxies (parsed from urls) together, using fwd as a forwarder. The dial order would be: fwd -> proxies[0] -> proxies[1] -> ... -> proxies[n-1], where n is the number of proxies.
Note that proxies specified in YAML use reverse ordering to go with the idiom "one over another".
func MakeProxyUsing ¶
MakeProxyUsing creates a load balancing Proxy from multiple proxies with specified strategy.
func ProxyFromDialer ¶
ProxyFromDialer creates a Proxy from a Dialer. The Dialer returned shouldn't be used for comparison.
type RelayOptions ¶
type RelayOptions struct {
// ConnIdle is the idle timeout when Relay starts.
// If both connections (local-side and remote-side) remains idle (no reads)
// for the duration of ConnIdle, both are closed and Relay ends.
ConnIdle time.Duration
// UplinkIdle is the idle timeout when the remote-side connection (downlink)
// closes. If the local-side connection (uplink) remains idle (no reads)
// for the duration of UplinkIdle, it is closed and Relay ends.
UplinkIdle time.Duration
// DownlinkIdle is the idle timeout when the local-side connection (uplink)
// closes. If the remote-side connection (downlink) remains idle (no reads)
// for the duration of DownlinkIdle, it is closed and Relay ends.
DownlinkIdle time.Duration
}
RelayOptions provides options for Relay.
type Service ¶
type Service interface {
// Name gets the name of the Service.
// Successive calls must return the same value.
Name() string
// Options returns a new options for unmarshaling.
// Options may return nil to indicate no options.
// If non-nil, the returned value must be a pointer to a struct.
// The returned value is sent to Context.Load later after unmarshaling.
Options() any
// Run starts a job.
Run(ctx Context)
}
A Service is something that does certain jobs.
type StringList ¶
type StringList []string
StringList is a helper type for unmarshaling a slice of string from YAML. When unmarshaling, it treats a string as a one-length slice of string.
func (*StringList) UnmarshalYAML ¶
func (s *StringList) UnmarshalYAML(v *yaml.Node) error
Source Files
Directories