core

README

Project V

Project V is a set of network tools that help you to build your own computer network. It secures your network connections and thus protects your privacy. See our website for more information.

License

The MIT License (MIT)

Credits

This repo relies on the following third-party projects:

• In production:
  • miekg/dns
  • gorilla/websocket
• For testing only:
  • h12w/socks

Documentation

Overview

Package core provides an entry point to use V2Ray core functionalities.

V2Ray makes it possible to accept incoming network connections with certain protocol, process the data, and send them through another connection with the same or a difference protocol on demand.

It may be configured to work with multiple protocols at the same time, and uses the internal router to tunnel through different inbound and outbound connections.

Index

• Constants
• Variables
• func Dial(ctx context.Context, v *Instance, dest net.Destination) (net.Conn, error)
• func LoadPlugins() error
• func RegisterConfigLoader(format *ConfigFormat) error
• func Version() string
• func VersionStatement() []string
• type Config
  • func LoadConfig(formatName string, filename string, input io.Reader) (*Config, error)
  • func (*Config) Descriptor() ([]byte, []int)
  • func (m *Config) GetApp() []*v2ray_core_common_serial.TypedMessage
  • func (m *Config) GetExtension() []*v2ray_core_common_serial.TypedMessage
  • func (m *Config) GetInbound() []*InboundHandlerConfig
  • func (m *Config) GetOutbound() []*OutboundHandlerConfig
  • func (m *Config) GetTransport() *v2ray_core_transport.Config
  • func (*Config) ProtoMessage()
  • func (m *Config) Reset()
  • func (m *Config) String() string
• type ConfigFormat
• type ConfigLoader
• type DNSClient
• type Dispatcher
• type Feature
• type GetMetadataFunc
• type InboundHandler
• type InboundHandlerConfig
  • func (*InboundHandlerConfig) Descriptor() ([]byte, []int)
  • func (m *InboundHandlerConfig) GetProxySettings() *v2ray_core_common_serial.TypedMessage
  • func (m *InboundHandlerConfig) GetReceiverSettings() *v2ray_core_common_serial.TypedMessage
  • func (m *InboundHandlerConfig) GetTag() string
  • func (*InboundHandlerConfig) ProtoMessage()
  • func (m *InboundHandlerConfig) Reset()
  • func (m *InboundHandlerConfig) String() string
• type InboundHandlerManager
• type Instance
  • func FromContext(ctx context.Context) *Instance
  • func MustFromContext(ctx context.Context) *Instance
  • func New(config *Config) (*Instance, error)
  • func (s *Instance) Close() error
  • func (s *Instance) CreateObject(config interface{}) (interface{}, error)
  • func (s *Instance) DNSClient() DNSClient
  • func (s *Instance) Dispatcher() Dispatcher
  • func (s *Instance) GetFeature(featureType interface{}) Feature
  • func (s *Instance) ID() uuid.UUID
  • func (s *Instance) InboundHandlerManager() InboundHandlerManager
  • func (s *Instance) OutboundHandlerManager() OutboundHandlerManager
  • func (s *Instance) PolicyManager() PolicyManager
  • func (s *Instance) RegisterFeature(feature interface{}, instance Feature) error
  • func (s *Instance) Router() Router
  • func (s *Instance) Start() error
• type OutboundHandler
• type OutboundHandlerConfig
  • func (*OutboundHandlerConfig) Descriptor() ([]byte, []int)
  • func (m *OutboundHandlerConfig) GetComment() string
  • func (m *OutboundHandlerConfig) GetExpire() int64
  • func (m *OutboundHandlerConfig) GetProxySettings() *v2ray_core_common_serial.TypedMessage
  • func (m *OutboundHandlerConfig) GetSenderSettings() *v2ray_core_common_serial.TypedMessage
  • func (m *OutboundHandlerConfig) GetTag() string
  • func (*OutboundHandlerConfig) ProtoMessage()
  • func (m *OutboundHandlerConfig) Reset()
  • func (m *OutboundHandlerConfig) String() string
• type OutboundHandlerManager
• type PluginMetadata
• type Policy
  • func DefaultPolicy() Policy
• type PolicyManager
• type Router
• type Server
• type TimeoutPolicy

Constants

const GetMetadataFuncName = "GetPluginMetadata"

GetMetadataFuncName is the name of the function in the plugin to return PluginMetadata.

Variables

var (
	// ErrNoClue is for the situation that existing information is not enough to make a decision. For example, Router may return this error when there is no suitable route.
	ErrNoClue = errors.New("not enough information for making a decision")
)

Functions

func Dial

func Dial(ctx context.Context, v *Instance, dest net.Destination) (net.Conn, error)

Dial provides an easy way for upstream caller to create net.Conn through V2Ray. It dispatches the request to the given destination by the given V2Ray instance. Since it is under a proxy context, the LocalAddr() and RemoteAddr() in returned net.Conn will not show real addresses being used for communication.

func LoadPlugins

func LoadPlugins() error

LoadPlugins loads all possible plugins in the 'plugin' directory.

func RegisterConfigLoader

func RegisterConfigLoader(format *ConfigFormat) error

RegisterConfigLoader add a new ConfigLoader.

func Version

func Version() string

Version returns V2Ray's version as a string, in the form of "x.y.z" where x, y and z are numbers. ".z" part may be omitted in regular releases.

func VersionStatement

func VersionStatement() []string

VersionStatement returns a list of strings representing the full version info.

Types

type Config

type Config struct {
	// Inbound handler configurations. Must have at least one item.
	Inbound []*InboundHandlerConfig `protobuf:"bytes,1,rep,name=inbound" json:"inbound,omitempty"`
	// Outbound handler configurations. Must have at least one item. The first item is used as default for routing.
	Outbound []*OutboundHandlerConfig `protobuf:"bytes,2,rep,name=outbound" json:"outbound,omitempty"`
	// App configuration. Must be one in the app directory.
	App []*v2ray_core_common_serial.TypedMessage `protobuf:"bytes,4,rep,name=app" json:"app,omitempty"`
	// Transport settings.
	Transport *v2ray_core_transport.Config `protobuf:"bytes,5,opt,name=transport" json:"transport,omitempty"`
	// Configuration for extensions. The config may not work if corresponding extension is not loaded into V2Ray.
	// V2Ray will ignore such config during initialization.
	Extension []*v2ray_core_common_serial.TypedMessage `protobuf:"bytes,6,rep,name=extension" json:"extension,omitempty"`
}

Config is the master config of V2Ray. V2Ray takes this config as input and functions accordingly.

func LoadConfig

func LoadConfig(formatName string, filename string, input io.Reader) (*Config, error)

LoadConfig loads config with given format from given source.

func (*Config) Descriptor

func (*Config) Descriptor() ([]byte, []int)

func (*Config) GetApp

func (m *Config) GetApp() []*v2ray_core_common_serial.TypedMessage

func (*Config) GetExtension

func (m *Config) GetExtension() []*v2ray_core_common_serial.TypedMessage

func (*Config) GetInbound

func (m *Config) GetInbound() []*InboundHandlerConfig

func (*Config) GetOutbound

func (m *Config) GetOutbound() []*OutboundHandlerConfig

func (*Config) GetTransport

func (m *Config) GetTransport() *v2ray_core_transport.Config

func (*Config) ProtoMessage

func (*Config) ProtoMessage()

func (*Config) Reset

func (m *Config) Reset()

func (*Config) String

func (m *Config) String() string

type ConfigFormat

type ConfigFormat struct {
	Name      string
	Extension []string
	Loader    ConfigLoader
}

ConfigFormat is a configurable format of V2Ray config file.

type ConfigLoader

type ConfigLoader func(input io.Reader) (*Config, error)

ConfigLoader is an utility to load V2Ray config from external source.

type DNSClient

type DNSClient interface {
	Feature
	LookupIP(host string) ([]net.IP, error)
}

DNSClient is a V2Ray feature for querying DNS information.

type Dispatcher

type Dispatcher interface {
	Feature

	// Dispatch returns a Ray for transporting data for the given request.
	Dispatch(ctx context.Context, dest net.Destination) (ray.InboundRay, error)
}

Dispatcher is a feature that dispatches inbound requests to outbound handlers based on rules. Dispatcher is required to be registered in a V2Ray instance to make V2Ray function properly.

type Feature

type Feature interface {
	common.Runnable
}

Feature is the interface for V2Ray features. All features must implement this interface. All existing features have an implementation in app directory. These features can be replaced by third-party ones.

type GetMetadataFunc

type GetMetadataFunc func() PluginMetadata

GetMetadataFunc is the type of the function in the plugin to return PluginMetadata.

type InboundHandler

type InboundHandler interface {
	common.Runnable
	// The tag of this handler.
	Tag() string

	// Deprecated. Do not use in new code.
	GetRandomInboundProxy() (interface{}, net.Port, int)
}

InboundHandler is the interface for handlers that process inbound connections.

type InboundHandlerConfig

type InboundHandlerConfig struct {
	// Tag of the inbound handler.
	Tag string `protobuf:"bytes,1,opt,name=tag" json:"tag,omitempty"`
	// Settings for how this inbound proxy is handled. Must be ReceiverConfig above.
	ReceiverSettings *v2ray_core_common_serial.TypedMessage `protobuf:"bytes,2,opt,name=receiver_settings,json=receiverSettings" json:"receiver_settings,omitempty"`
	// Settings for inbound proxy. Must be one of the inbound proxies.
	ProxySettings *v2ray_core_common_serial.TypedMessage `protobuf:"bytes,3,opt,name=proxy_settings,json=proxySettings" json:"proxy_settings,omitempty"`
}

func (*InboundHandlerConfig) Descriptor

func (*InboundHandlerConfig) Descriptor() ([]byte, []int)

func (*InboundHandlerConfig) GetProxySettings

func (m *InboundHandlerConfig) GetProxySettings() *v2ray_core_common_serial.TypedMessage

func (*InboundHandlerConfig) GetReceiverSettings

func (m *InboundHandlerConfig) GetReceiverSettings() *v2ray_core_common_serial.TypedMessage

func (*InboundHandlerConfig) GetTag

func (m *InboundHandlerConfig) GetTag() string

func (*InboundHandlerConfig) ProtoMessage

func (*InboundHandlerConfig) ProtoMessage()

func (*InboundHandlerConfig) Reset

func (m *InboundHandlerConfig) Reset()

func (*InboundHandlerConfig) String

func (m *InboundHandlerConfig) String() string

type InboundHandlerManager

type InboundHandlerManager interface {
	Feature
	// GetHandlers returns an InboundHandler for the given tag.
	GetHandler(ctx context.Context, tag string) (InboundHandler, error)
	// AddHandler adds the given handler into this InboundHandlerManager.
	AddHandler(ctx context.Context, handler InboundHandler) error

	// RemoveHandler removes a handler from InboundHandlerManager.
	RemoveHandler(ctx context.Context, tag string) error
}

InboundHandlerManager is a feature that managers InboundHandlers.

type Instance

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

Instance combines all functionalities in V2Ray.

func FromContext

func FromContext(ctx context.Context) *Instance

FromContext returns an Instance from the given context, or nil if the context doesn't contain one.

func MustFromContext

func MustFromContext(ctx context.Context) *Instance

MustFromContext returns an Instance from the given context, or panics if not present.

func New

func New(config *Config) (*Instance, error)

New returns a new V2Ray instance based on given configuration. The instance is not started at this point. To make sure V2Ray instance works properly, the config must contain one Dispatcher, one InboundHandlerManager and one OutboundHandlerManager. Other features are optional.

func (*Instance) Close

func (s *Instance) Close() error

Close shutdown the V2Ray instance.

func (*Instance) CreateObject

func (s *Instance) CreateObject(config interface{}) (interface{}, error)

func (*Instance) DNSClient

func (s *Instance) DNSClient() DNSClient

DNSClient returns the DNSClient used by this Instance. The returned DNSClient is always functional.

func (*Instance) Dispatcher

func (s *Instance) Dispatcher() Dispatcher

Dispatcher returns the Dispatcher used by this Instance. If Dispatcher was not registered before, the returned value doesn't work, although it is not nil.

func (*Instance) GetFeature

func (s *Instance) GetFeature(featureType interface{}) Feature

GetFeature returns a feature that was registered in this Instance. Nil if not found. The returned Feature must implement common.HasType and whose type equals the given feature type.

func (*Instance) ID

func (s *Instance) ID() uuid.UUID

ID returns an unique ID for this V2Ray instance.

func (*Instance) InboundHandlerManager

func (s *Instance) InboundHandlerManager() InboundHandlerManager

InboundHandlerManager returns the InboundHandlerManager used by this Instance. If InboundHandlerManager was not registered before, the returned value doesn't work.

func (*Instance) OutboundHandlerManager

func (s *Instance) OutboundHandlerManager() OutboundHandlerManager

OutboundHandlerManager returns the OutboundHandlerManager used by this Instance. If OutboundHandlerManager was not registered before, the returned value doesn't work.

func (*Instance) PolicyManager

func (s *Instance) PolicyManager() PolicyManager

PolicyManager returns the PolicyManager used by this Instance. The returned PolicyManager is always functional.

func (*Instance) RegisterFeature

func (s *Instance) RegisterFeature(feature interface{}, instance Feature) error

RegisterFeature registers the given feature into V2Ray. If feature is one of the following types, the corressponding feature in this Instance will be replaced: DNSClient, PolicyManager, Router, Dispatcher, InboundHandlerManager, OutboundHandlerManager.

func (*Instance) Router

func (s *Instance) Router() Router

Router returns the Router used by this Instance. The returned Router is always functional.

func (*Instance) Start

func (s *Instance) Start() error

Start starts the V2Ray instance, including all registered features. When Start returns error, the state of the instance is unknown. A V2Ray instance can be started only once. Upon closing, the instance is not guaranteed to start again.

type OutboundHandler

type OutboundHandler interface {
	common.Runnable
	Tag() string
	Dispatch(ctx context.Context, outboundRay ray.OutboundRay)
}

OutboundHandler is the interface for handlers that process outbound connections.

type OutboundHandlerConfig

type OutboundHandlerConfig struct {
	// Tag of this outbound handler.
	Tag string `protobuf:"bytes,1,opt,name=tag" json:"tag,omitempty"`
	// Settings for how to dial connection for this outbound handler. Must be SenderConfig above.
	SenderSettings *v2ray_core_common_serial.TypedMessage `protobuf:"bytes,2,opt,name=sender_settings,json=senderSettings" json:"sender_settings,omitempty"`
	// Settings for this outbound proxy. Must be one of the outbound proxies.
	ProxySettings *v2ray_core_common_serial.TypedMessage `protobuf:"bytes,3,opt,name=proxy_settings,json=proxySettings" json:"proxy_settings,omitempty"`
	// If not zero, this outbound will be expired in seconds. Not used for now.
	Expire int64 `protobuf:"varint,4,opt,name=expire" json:"expire,omitempty"`
	// Comment of this outbound handler. Not used for now.
	Comment string `protobuf:"bytes,5,opt,name=comment" json:"comment,omitempty"`
}

func (*OutboundHandlerConfig) Descriptor

func (*OutboundHandlerConfig) Descriptor() ([]byte, []int)

func (*OutboundHandlerConfig) GetComment

func (m *OutboundHandlerConfig) GetComment() string

func (*OutboundHandlerConfig) GetExpire

func (m *OutboundHandlerConfig) GetExpire() int64

func (*OutboundHandlerConfig) GetProxySettings

func (m *OutboundHandlerConfig) GetProxySettings() *v2ray_core_common_serial.TypedMessage

func (*OutboundHandlerConfig) GetSenderSettings

func (m *OutboundHandlerConfig) GetSenderSettings() *v2ray_core_common_serial.TypedMessage

func (*OutboundHandlerConfig) GetTag

func (m *OutboundHandlerConfig) GetTag() string

func (*OutboundHandlerConfig) ProtoMessage

func (*OutboundHandlerConfig) ProtoMessage()

func (*OutboundHandlerConfig) Reset

func (m *OutboundHandlerConfig) Reset()

func (*OutboundHandlerConfig) String

func (m *OutboundHandlerConfig) String() string

type OutboundHandlerManager

type OutboundHandlerManager interface {
	Feature
	// GetHandler returns an OutboundHandler will given tag.
	GetHandler(tag string) OutboundHandler
	// GetDefaultHandler returns the default OutboundHandler. It is usually the first OutboundHandler specified in the configuration.
	GetDefaultHandler() OutboundHandler
	// AddHandler adds a handler into this OutboundHandlerManager.
	AddHandler(ctx context.Context, handler OutboundHandler) error

	// RemoveHandler removes a handler from OutboundHandlerManager.
	RemoveHandler(ctx context.Context, tag string) error
}

OutboundHandlerManager is a feature that manages OutboundHandlers.

type PluginMetadata

type PluginMetadata struct {
	// Name of the plugin
	Name string
}

PluginMetadata contains some brief information regarding a plugin.

type Policy

type Policy struct {
	Timeouts TimeoutPolicy // Timeout settings
}

Policy is session based settings for controlling V2Ray requests. It contains various settings (or limits) that may differ for different users in the context.

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy returns the Policy when user is not specified.

type PolicyManager

type PolicyManager interface {
	Feature

	// ForLevel returns the Policy for the given user level.
	ForLevel(level uint32) Policy
}

PolicyManager is a feature that provides Policy for the given user by its id or level.

type Router

type Router interface {
	Feature

	// PickRoute returns a tag of an OutboundHandler based on the given context.
	PickRoute(ctx context.Context) (string, error)
}

Router is a feature to choose a outbound tag for the given request.

type Server

type Server interface {
	common.Runnable
}

Server is an instance of V2Ray. At any time, there must be at most one Server instance running. Deprecated. Use Instance directly.

type TimeoutPolicy

type TimeoutPolicy struct {
	// Timeout for handshake phase in a connection.
	Handshake time.Duration
	// Timeout for connection being idle, i.e., there is no egress or ingress traffic in this connection.
	ConnectionIdle time.Duration
	// Timeout for an uplink only connection, i.e., the downlink of the connection has been closed.
	UplinkOnly time.Duration
	// Timeout for an downlink only connection, i.e., the uplink of the connection has been closed.
	DownlinkOnly time.Duration
}

TimeoutPolicy contains limits for connection timeout.