Xray

https://github.com/xtls/xray-core
Admin
Project X, originating from the XTLS protocol, offers a suite of network tools including Xray-core...
Tokens:903,183
Snippets:5,697
Trust Score:8.8
License:MPL-2.0
Update:3 days ago
Show doc for...
Tokens:
Raw
### Usage example: start metrics handler

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/metrics.md

Shows how to create and start a MetricsHandler with a specific tag and listen address. Includes a JSON config example and a curl command to access the metrics endpoint.

```go
// JSON config:
// {
//   "metrics": {
//     "tag": "metrics",
//     "listen": "127.0.0.1:9999"
//   }
// }
// Then: curl http://127.0.0.1:9999/debug/vars

import (
	"context"

	"github.com/xtls/xray-core/app/metrics"
	"github.com/xtls/xray-core/core"
)

func startMetrics(v *core.Instance) error {
	handler, err := metrics.NewMetricsHandler(context.Background(), &metrics.Config{
		Tag:    "metrics",
		Listen: "127.0.0.1:9999",
	})
	if err != nil {
		return err
	}
	return handler.Start()
}
```

--------------------------------

### Full lifecycle of an embedded instance in Go

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

Shows how to load a protobuf-serialized config, create an instance with core.New, start it, and defer Close. Use when embedding Xray-core in a Go application. The example includes error handling with log.Fatal and a comment showing how to dial through the instance.

```go
package main

import (
	"log"

	"github.com/xtls/xray-core/core"
	"github.com/xtls/xray-core/main/confloader" // registers JSON/YAML/TOML loaders
)

func main() {
	// Load a config from a protobuf-serialized core.Config
	configBytes := loadConfigBytes() // []byte
	config, err := core.LoadConfig("protobuf", bytes.NewReader(configBytes))
	if err != nil {
		log.Fatal(err)
	}

	instance, err := core.New(config)
	if err != nil {
		log.Fatal(err)
	}

	if err := instance.Start(); err != nil {
		log.Fatal(err)
	}
	defer instance.Close()

	// Dial through the instance...
	// conn, err := core.Dial(ctx, instance, dest)
}
```

--------------------------------

### core.StartInstance(configFormat, configBytes)

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-helpers.md

Starts a new Xray instance from the given configuration bytes. Returns an error if the config parse, instance creation, or start fails.

```APIDOC
## core.StartInstance(configFormat, configBytes)

### Description
Starts a new Xray instance from the given configuration bytes. Returns an error if the config parse, instance creation, or start fails.

### Method
Function

### Signature
func StartInstance(configFormat string, configBytes []byte) (*Instance, error)

### Parameters
- **configFormat** (string) - Required - The format of the configuration, e.g., "protobuf".
- **configBytes** ([]byte) - Required - The configuration data.

### Returns
- ***Instance** - The started Xray instance.
- **error** - An error if the config parse, instance creation, or start fails.

### Example
```go
instance, err := core.StartInstance("protobuf", configBytes)
```
```

--------------------------------

### Instance.Start()

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

The Start method starts the instance and all registered features.

```APIDOC
## Instance.Start

### Description
Starts the instance and all registered features. This is a stable API (`xray:api:stable`).

### Method
`Start()`

### Signature
`func (s *Instance) Start() error`

### Returns
- `error` - Returns `nil` if the instance started successfully, otherwise an error.
```

--------------------------------

### Usage Example

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/commander.md

Example of how to register the API via JSON config and query stats using the gRPC client.

```APIDOC
## Usage Example

### Description
Example of how to register the API via JSON config and query stats using the gRPC client.

### JSON Config
```json
{
  "api": {
    "tag": "api",
    "listen": "127.0.0.1:8080",
    "services": ["HandlerService", "LoggerService", "StatsService", "RoutingService"]
  }
}
```

### Go Code
```go
import (
	"context"

	"github.com/xtls/xray-core/app/commander"
	statscommand "github.com/xtls/xray-core/app/stats/command"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func queryStats(addr string) {
	conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	client := statscommand.NewStatsServiceClient(conn)
	resp, err := client.GetStats(context.Background(), &statscommand.GetStatsRequest{
		Name:  "outbound>>>proxy>>>traffic>>>uplink",
		Reset: false,
	})
	if err != nil {
		log.Fatal(err) // codes.NotFound when the counter does not exist
	}
	println("value:", resp.GetStat().GetValue())
}
```
```

--------------------------------

### Start

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

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

```APIDOC
## Start

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

### Method
Start

### Signature
func (s *Instance) Start() error

### Parameters
- (receiver) (*Instance) - Required - The instance to start.

### Returns
- error - The first error produced by any feature's Start(), or nil. On error the state of the instance is undefined. A started instance logs "Xray 26.9.30 started" at warning level.

### Errors
- error from any failing feature Start(); the instance is not guaranteed to be restartable after Close().
```

--------------------------------

### StartInstance

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-helpers.md

Documentation for the StartInstance function, which starts a new Xray instance with given serialized config.

```APIDOC
## StartInstance

### Description
Starts a new Xray instance with given serialized config. By default Xray only supports config in protobuf format, i.e., configFormat = "protobuf". Caller needs to load other packages to add JSON support.

### Method
Function

### Endpoint
`func StartInstance(configFormat string, configBytes []byte) (*Instance, error)`

### Parameters
- **configFormat** (`string`) - Required - Format name, e.g. `"protobuf"`, `"json"`, `"auto"`.
- **configBytes** (`[]byte`) - Required - Serialized config bytes.

### Returns
- `*Instance` - An instance that has already been `Start()`ed.
- `error` - Error if any.

### Errors
- Errors from `LoadConfig`, `New`, or `Start`. On any failure the partially-built instance is not returned.

### Notes
- This API is marked as stable (`xray:api:stable`).
```

--------------------------------

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

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

Creates a new Xray instance from the given configuration. The instance is not started until explicitly started. The config must contain required components for a functional instance.

```APIDOC
## New(config *Config) (*Instance, error)

### Description
Creates a new Xray instance based on the provided configuration. The instance is not started at this point. The config must contain one Dispatcher, one InboundHandlerManager, and one OutboundHandlerManager for proper operation.

### Method
Constructor

### Signature
```go
func New(config *Config) (*Instance, error)
```

### Parameters
- **config** (`*Config`) - Required - Master Xray configuration. Must contain at least one inbound and one outbound handler config per the protobuf definition, plus apps for Dispatcher, InboundManager, and OutboundManager for a functional instance.

### Returns
- **(*Instance, error)** - A fully constructed but not started instance. The error is non-nil when config parsing of embedded TypedMessage app settings fails, when a config type is not registered with common.RegisterConfig, when not all required dependencies are resolved, or when inbound/outbound handler creation fails.

### Behavior Notes
During construction, the following steps occur:
1. platform.ReloadEnvSettings() is called; failure aborts with error "failed to reload environment settings".
2. The context is seeded with a "cone" value based on the xray.cone.disabled environment flag.
3. Every config.App entry is instantiated via CreateObject, and any object implementing features.Feature is added via AddFeature.
4. Essential features are added if absent: a local DNS client (localdns.New()), policy.DefaultManager{}, routing.DefaultRouter{}, and stats.NoopManager{}.
5. internet.InitSystemDialer is wired with the DNS client and outbound manager.
6. Inbound handlers and then outbound handlers are created and added.
```

--------------------------------

### Lifecycle and type methods

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/dns.md

Provides the Type, Start, and Close methods for the DNS server. Start and Close return nil.

```go
func (*DNS) Type() interface{} // dns.ClientType()
func (s *DNS) Start() error    // nil
func (s *DNS) Close() error    // nil
```

--------------------------------

### Load config programmatically with core.LoadConfig

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/infra-conf.md

Programmatically loads a configuration file using core.LoadConfig with the "auto" format, which detects the file extension (.json, .jsonc, .yaml, .toml). Requires importing the blank import "github.com/xtls/xray-core/main/distro/all" to register the JSON builder. The example creates a core instance, starts it, and defers Close().

```go
package main

import (
	"log"

	_ "github.com/xtls/xray-core/main/distro/all" // registers the JSON builder
	"github.com/xtls/xray-core/core"
)

func main() {
	// Load one or more .json/.jsonc/.yaml/.toml files; "auto" detects by extension
	config, err := core.LoadConfig("auto", cmdarg.Arg{"config.json"})
	if err != nil {
		log.Fatal("load: ", err)
	}
	instance, err := core.New(config)
	if err != nil {
		log.Fatal("create: ", err)
	}
	if err := instance.Start(); err != nil {
		log.Fatal("start: ", err)
	}
	defer instance.Close()
}
```

--------------------------------

### List and override outbound handlers with outbound.Manager

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/proxyman.md

Shows how to access the outbound manager from a core instance, list handlers, select by prefix, get the default handler, and programmatically add a new outbound handler. The example uses the outbound.Manager feature interface and core.AddOutboundHandler.

```go
import (
	"context"

	"github.com/xtls/xray-core/app/proxyman/outbound"
	"github.com/xtls/xray-core/core"
	"github.com/xtls/xray-core/features/outbound"
)

func listAndOverride(v *core.Instance) {
	fs := v.GetFeature(outbound.ManagerType()).(outbound.Manager)

	// List handlers
	for _, h := range fs.ListHandlers(context.Background()) {
		println("outbound:", h.Tag())
	}

	// Select by prefix selector (used by balancers/observatory)
	if sel, ok := fs.(outbound.HandlerSelector); ok {
		tags := sel.Select([]string{"proxy"})
		_ = tags
	}

	// The default handler is the first one registered
	d := fs.GetDefaultHandler()
	_ = d
}

// Build a handler programmatically and attach it:
func addHandler(v *core.Instance, hc *core.OutboundHandlerConfig) error {
	return core.AddOutboundHandler(v, hc)
}
```

--------------------------------

### Lifecycle Methods: Type, Start, Close

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/dns.md

Lifecycle methods for the DNS server: Type returns the client type, Start initializes the server, and Close shuts it down.

```APIDOC
## Lifecycle Methods

### Type

#### Description
Returns the client type.

#### Signature
`func (*DNS) Type() interface{}`

#### Returns
- `interface{}` - The client type, typically `dns.ClientType()`.

### Start

#### Description
Starts the DNS server.

#### Signature
`func (s *DNS) Start() error`

#### Returns
- `error` - Always `nil`.

### Close

#### Description
Closes the DNS server.

#### Signature
`func (s *DNS) Close() error`

#### Returns
- `error` - Always `nil`.
```

--------------------------------

### Usage example: setting up a file-based logger

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/log.md

Shows how to create a log.Instance with file-based error and access logs, warning severity, DNS logging enabled, and half IP masking. The New function registers the handler process-wide.

```go
import (
	"context"

	applog "github.com/xtls/xray-core/app/log"
	"github.com/xtls/xray-core/common/log"
)

func setupLogger(ctx context.Context) *applog.Instance {
	cfg := &applog.Config{
		ErrorLogType:  applog.LogType_File,
		ErrorLogPath:  "/var/log/xray/error.log",
		ErrorLogLevel: log.Severity_Warning,
		AccessLogType: applog.LogType_File,
		AccessLogPath: "/var/log/xray/access.log",
		EnableDnsLog:  true,
		MaskAddress:   "half",
	}
	inst, err := applog.New(ctx, cfg)
	if err != nil {
		panic(err)
	}
	// applog.New already called log.RegisterHandler(inst), so errors.Log*
	// calls in every package now flow through this instance.
	return inst
}
```

--------------------------------

### Build and dial a destination

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/net.md

Usage example showing how to build a destination and dial it.

```APIDOC
## Build and dial a destination

### Description
Example of building a destination and dialing it using the core package.

### Code
```go
package main

import (
	"context"
	"log"

	"github.com/xtls/xray-core/common/net"
	"github.com/xtls/xray-core/core"
)

func main() {
	// Parse a full destination string
	dest, err := net.ParseDestination("tcp:example.com:443")
	if err != nil {
		log.Fatal(err) // bad host:port
	}

	// Build one programmatically
	dest = net.TCPDestination(net.ParseAddress("1.1.1.1"), net.Port(853))

	instance, _ := core.StartInstance("protobuf", cfgBytes)
	conn, err := core.Dial(context.Background(), instance, dest)
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	// ...
}
```
```

--------------------------------

### Usage example: queryOnce and serverFor

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/dns.md

Shows how to create a DNS app, perform a lookup with IP options, handle errors, and create a custom nameserver programmatically. The `serverFor` function uses `net.ParseDestination` and `dnsapp.NewServer`.

```go
import (
	"context"

	dnsapp "github.com/xtls/xray-core/app/dns"
	"github.com/xtls/xray-core/common/net"
	"github.com/xtls/xray-core/features/dns"
)

func queryOnce(ctx context.Context, cfg *dnsapp.Config) {
	server, err := dnsapp.New(ctx, cfg)
	if err != nil {
		log.Fatal(err)
	}

	ips, ttl, err := server.LookupIP("example.com", dns.IPOption{
		IPv4Enable: true,
		IPv6Enable: true,
		FakeEnable: true,
	})
	switch {
	case err == dns.ErrEmptyResponse:
		println("no answers")
	case err != nil:
		println("lookup failed:", err.Error())
	default:
		println("ttl:", ttl, "first IP:", ips[0].String())
	}
}

// Create a custom nameserver programmatically:
func serverFor(ctx context.Context, dispatcher routing.Dispatcher) (dnsapp.Server, error) {
	dest, _ := net.ParseDestination("udp:8.8.8.8:53")
	return dnsapp.NewServer(ctx, dest, dispatcher, false, false, 0, nil)
}
```

--------------------------------

### Instance.IsRunning()

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

The IsRunning method returns whether the instance has been started.

```APIDOC
## Instance.IsRunning

### Description
Returns whether the instance has been started.

### Method
`IsRunning()`

### Signature
`func (server *Instance) IsRunning() bool`

### Returns
- `bool` - `true` if the instance has been started, `false` otherwise.
```

--------------------------------

### Example interface list output

Source: https://github.com/xtls/xray-core/blob/main/proxy/tun/README.md

Sample output from the route print command showing the Xray Tunnel interface.

```text
===========================================================================
Interface List
  8...cc cc cc cc cc cc ......Realtek PCIe GbE Family Controller
 47...........................Xray Tunnel
  1...........................Software Loopback Interface 1
===========================================================================
```

--------------------------------

### Go client example for Stats and Routing services

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/endpoints.md

Shows how to dial the xray-core gRPC API at 127.0.0.1:8080, query traffic stats with GetStats, and test a route decision with TestRoute. Requires the stats and router command packages and uses insecure credentials.

```go
package main

import (
	"context"
	"log"

	statscommand "github.com/xtls/xray-core/app/stats/command"
	routercommand "github.com/xtls/xray-core/app/router/command"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/status"
)

func main() {
	conn, err := grpc.Dial("127.0.0.1:8080", grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	// Stats
	stats := statscommand.NewStatsServiceClient(conn)
	resp, err := stats.GetStats(context.Background(), &statscommand.GetStatsRequest{
		Name:  "outbound>>>proxy>>>traffic>>>uplink",
		Reset: false,
	})
	if err != nil {
		if status.Code(err) == codes.NotFound {
			log.Print("counter not found")
		} else {
			log.Fatal(err)
		}
	} else {
		log.Printf("uplink bytes: %d", resp.GetStat().GetValue())
	}
}

// Test a route decision:
func testRoute(conn *grpc.ClientConn) {
	router := routercommand.NewRoutingServiceClient(conn)
	ctx, _ := context.WithTimeout(context.Background(), 5*time.Second)
	out, err := router.TestRoute(ctx, &routercommand.TestRouteRequest{
		RoutingContext: &routercommand.RoutingContext{
			TargetDomain: "example.com",
			InboundTag:   "in-0",
		},
		FieldSelectors: []string{"outbound", "outbound_group"},
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("picked outbound: %s", out.OutboundTag)
}
```

--------------------------------

### Instance Methods

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/policy.md

Methods available on the Policy manager Instance: Type, ForLevel, ForSystem, Start, and Close.

```APIDOC
## Instance Methods

### Description
Methods to retrieve session and system policies, and lifecycle management.

### Methods

#### Type
- **Signature**: `func (*Instance) Type() interface{}`
- **Behavior**: Returns `policy.ManagerType()`.

#### ForLevel
- **Signature**: `func (m *Instance) ForLevel(level uint32) policy.Session`
- **Behavior**: Returns the merged session policy for a level, or `policy.SessionDefault()` when unconfigured.

#### ForSystem
- **Signature**: `func (m *Instance) ForSystem() policy.System`
- **Behavior**: Returns `policy.System{}` when unconfigured (`SystemPolicy` nil).

#### Start / Close
- **Signature**: lifecycle methods
- **Behavior**: Both return nil.
```

--------------------------------

### Usage example: querying stats via gRPC

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/commander.md

Shows how to connect to the Commander's gRPC API and query a traffic stat. Includes a JSON config example for enabling the API. The code dials the address, creates a StatsService client, and calls GetStats with a specific counter name. Errors are fatal, and a NotFound code is returned when the counter does not exist.

```go
// Register via JSON config:
//
// {
//   "api": {
//     "tag": "api",
//     "listen": "127.0.0.1:8080",
//     "services": ["HandlerService", "LoggerService", "StatsService", "RoutingService"]
//   }
// }

import (
	"context"

	"github.com/xtls/xray-core/app/commander"
	statscommand "github.com/xtls/xray-core/app/stats/command"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func queryStats(addr string) {
	conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	client := statscommand.NewStatsServiceClient(conn)
	resp, err := client.GetStats(context.Background(), &statscommand.GetStatsRequest{
		Name:  "outbound>>>proxy>>>traffic>>>uplink",
		Reset: false,
	})
	if err != nil {
		log.Fatal(err) // codes.NotFound when the counter does not exist
	}
	println("value:", resp.GetStat().GetValue())
}
```

--------------------------------

### Usage example: create Policy manager and query policies

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/policy.md

Shows how to create a Policy manager with a custom level and system policy, then retrieve the merged session and system policies. The output comments show Handshake as "30s", ConnectionIdle as "2m0s", and OutboundDownlink as true.

```go
import (
	"context"

	policyapp "github.com/xtls/xray-core/app/policy"
	"github.com/xtls/xray-core/features/policy"
)

func checkPolicy(ctx context.Context) {
	cfg := &policyapp.Config{
		Level: map[uint32]*policyapp.Policy{
			0: {
				Timeout: &policyapp.Policy_Timeout{
					Handshake:      &policyapp.Second{Value: 30},
					ConnectionIdle: &policyapp.Second{Value: 120},
				},
			},
		},
		System: &policyapp.SystemPolicy{
			Stats: &policyapp.SystemPolicy_Stats{
				InboundUplink:    true,
				OutboundDownlink: true,
			},
		},
	}
	m, err := policyapp.New(ctx, cfg)
	if err != nil {
		log.Fatal(err)
	}

	sess := m.ForLevel(0)
	println(sess.Timeouts.Handshake.String())     // "30s"
	println(sess.Timeouts.ConnectionIdle.String()) // "2m0s"
	sys := m.ForSystem()
	println(sys.Stats.OutboundDownlink) // true
}
```

--------------------------------

### One-shot instance from bytes with cleanup

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-helpers.md

Creates a one-shot Xray instance from protobuf config bytes and cleans it up with defer. Logs fatal on config parse, instance creation, or start failure; checks IsRunning() to verify the instance is active.

```go
import (
	"log"

	"github.com/xtls/xray-core/core"
)

func runOnce(configBytes []byte) {
	instance, err := core.StartInstance("protobuf", configBytes)
	if err != nil {
		log.Fatal(err) // config parse, instance creation, or start failure
	}
	defer instance.Close()

	if !instance.IsRunning() {
		log.Print("instance not running")
	}
	// ... use instance
}
```

--------------------------------

### Add on-link route

Source: https://github.com/xtls/xray-core/blob/main/proxy/tun/README.md

Example command to add an on-link route through the identified adapter interface.

```bash
route add 1.1.1.1 mask 255.0.0.0 0.0.0.0 if 47
```

--------------------------------

### Usage Example

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/stats.md

Code snippets demonstrating how to use the stats.Manager interface to read traffic counters and subscribe to channels.

```APIDOC
## GetOrRegisterCounter

### Description
Retrieves or registers a counter for the given name. The counter is used to track traffic statistics for a user or outbound.

### Method
GetOrRegisterCounter

### Parameters
- **name** (string) - Required - The counter name, e.g., "user>>>email>>>traffic>>>uplink".

### Returns
- **counter** (Counter) - The counter object, or nil if not available.
- **error** (error) - An error if the operation fails.

### Example
```go
up, _ := sm.GetOrRegisterCounter("user>>>" + email + ">>>traffic>>>uplink")
```

```

```APIDOC
## GetOrRegisterChannel

### Description
Retrieves or registers a channel for the given name. The channel is used to subscribe to events.

### Method
GetOrRegisterChannel

### Parameters
- **name** (string) - Required - The channel name.

### Returns
- **channel** (Channel) - The channel object.
- **error** (error) - An error if the operation fails.

### Example
```go
ch, _ := sm.GetOrRegisterChannel(name)
```

```

```APIDOC
## SubscribeRunnableChannel

### Description
Subscribes to a channel and returns a subscription that can be used to receive messages.

### Method
SubscribeRunnableChannel

### Parameters
- **ch** (Channel) - The channel to subscribe to.

### Returns
- **sub** (Subscription) - The subscription object.
- **error** (error) - An error if the subscription fails.

### Example
```go
sub, err := feature_stats.SubscribeRunnableChannel(ch)
```

```

```APIDOC
## UnsubscribeClosableChannel

### Description
Unsubscribes from a channel and closes the subscription.

### Method
UnsubscribeClosableChannel

### Parameters
- **ch** (Channel) - The channel to unsubscribe from.
- **sub** (Subscription) - The subscription to close.

### Example
```go
defer feature_stats.UnsubscribeClosableChannel(ch, sub)
```

```

--------------------------------

### NewWebhookNotifier(cfg)

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/router.md

Documentation for the NewWebhookNotifier function and its usage example.

```APIDOC
## NewWebhookNotifier(cfg)

### Description
Creates a notifier that fires per matching route, posting route metadata to the configured URL.

### Method
Function

### Signature
`NewWebhookNotifier(cfg)`

### Parameters
- **cfg** (config) - Required - Configuration for the webhook notifier.

### Behavior
- The notifier is fired per matching route via `rule.Webhook.Fire(originalCtx, tag)`.
- It posts route metadata to the configured URL.

### Usage Example
```go
import (
	"github.com/xtls/xray-core/core"
	"github.com/xtls/xray-core/features/routing"
)

func routeOnce(v *core.Instance, ctx routing.Context) (string, error) {
	router := v.GetFeature(routing.RouterType())
	if router == nil {
		return "", errors.New("no router; default router returns ErrNoClue")
	}
	route, err := router.(routing.Router).PickRoute(ctx)
	if err != nil {
		return "", err // common.ErrNoClue when unmatched
	}
	return route.GetOutboundTag(), nil
}
```
```

--------------------------------

### Commander Methods

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/commander.md

Methods available on the Commander struct: Type, Start, and Close.

```APIDOC
## Commander Methods

### Description
Methods available on the Commander struct.

### Type
`func (c *Commander) Type() interface{}`
Returns `(*Commander)(nil)`.

### Start
`func (c *Commander) Start() error`
Creates `grpc.NewServer()`, registers services, binds: TCP/Unix socket when `listen` set (`internet.ListenSystem`), otherwise registers an in-process `OutboundListener` under outbound tag `c.tag` (removing any previous handler with that tag first).

### Close
`func (c *Commander) Close() error`
`grpc.Server.Stop()` if running.
```

--------------------------------

### Add IPv6 routes to utun interface

Source: https://github.com/xtls/xray-core/blob/main/proxy/tun/README.md

Example commands to route specific IPv6 hosts through a designated utun interface.

```bash
sudo route add -inet6 -host 2606:4700:4700::1111 -iface utun10
sudo route add -inet6 -host 2606:4700:4700::1001 -iface utun10
```

--------------------------------

### Usage example: creating a duplex link pair and reading with timeout

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/transport-pipe.md

Shows how to create two pipes to form a duplex link pair, write to the outbound side, read from the inbound side, and use ReadMultiBufferTimeout for buffered reads with a timeout.

```go
package main

import (
	"context"

	"github.com/xtls/xray-core/common/buf"
	"github.com/xtls/xray-core/transport"
	"github.com/xtls/xray-core/transport/pipe"
)

func example() {
	// Two pipes = one duplex link pair (as the dispatcher does)
	uplinkReader, uplinkWriter := pipe.New(pipe.WithoutSizeLimit())
	downlinkReader, downlinkWriter := pipe.New()

	inboundLink := &transport.Link{Reader: downlinkReader, Writer: uplinkWriter}
	outboundLink := &transport.Link{Reader: uplinkReader, Writer: downlinkWriter}

	// Write into the outbound side, read from the inbound side:
	outboundLink.Writer.WriteMultiBuffer(buf.MultiBuffer{buf.FromBytes([]byte("hi"))})
	mb, _ := inboundLink.Reader.ReadMultiBuffer()
	println(mb.String()) // "hi"
}

// Buffered pipe reads with timeout:
func readWithTimeout(ctx context.Context, r *pipe.Reader) {
	mb, err := r.ReadMultiBufferTimeout(200 * 1e6) // ns
	_ = mb
	_ = err
}
```

--------------------------------

### Usage example: pipeCopy function

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/buffer.md

Shows a loop that reads from a buf.Reader and writes to a buf.Writer, handling empty buffers and EOF. It returns nil on EOF and propagates other errors.

```go
import (
	"io"

	"github.com/xtls/xray-core/common/buf"
)

func pipeCopy(r buf.Reader, w buf.Writer) error {
	for {
		mb, err := r.ReadMultiBuffer()
		if !mb.IsEmpty() {
			if werr := w.WriteMultiBuffer(mb); werr != nil {
				return werr
			}
		}
		if err != nil {
			if err == io.EOF {
				return nil
			}
			return err
		}
	}
}

```

--------------------------------

### Add IPv4 route to utun interface

Source: https://github.com/xtls/xray-core/blob/main/proxy/tun/README.md

Example command to route a specific IPv4 network through a designated utun interface.

```bash
sudo route add -net 1.1.1.0/24 -iface utun10
```

--------------------------------

### Family-safe access with error handling

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/net.md

Usage example showing safe access to address family-specific methods and port validation.

```APIDOC
## Family-safe access with error handling

### Description
Example of safely accessing address family-specific fields and validating ports.

### Code
```go
import "github.com/xtls/xray-core/common/net"

func hostOf(d net.Destination) string {
	// Guard family-specific accessors to avoid panics:
	if d.Address.Family().IsDomain() {
		return d.Address.Domain()
	}
	return d.Address.IP().String()
}

func validatePort(raw string) (net.Port, error) {
	p, err := net.PortFromString(raw)
	if err != nil {
		return 0, err // "invalid port range: <raw>"
	}
	return p, nil
}
```
```

--------------------------------

### Runnable and Closable interfaces

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

Defines the common.Runnable and Closable interfaces that Server embeds. Start() begins the object and returns nil on success; Close() releases all resources including goroutines.

```go
type Runnable interface {
	// Start starts the runnable object. Upon the method returning nil, the object begins to function properly.
	Start() error

	Closable
}

type Closable interface {
	// Close release all resources used by this object, including goroutines.
	Close() error
}
```

--------------------------------

### InboundDetourConfig JSON example

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/infra-conf.md

JSON configuration for an inbound detour. The `sniffing` section maps `destOverride` strings: `http`, `tls|https|ssl`, `quic`, `fakedns|fakedns+others`; unknown protocol triggers error `"unknown protocol: <p>"`.

```json
{
  "tag": "in-0",
  "listen": "127.0.0.1",        // + optional ":port"
  "port": 1080,
  "protocol": "socks",
  "settings": { ... },          // protocol-specific
  "streamSettings": { ... },    // transport
  "sniffing": { "enabled": true, "destOverride": ["http", "tls"], "metadataOnly": false, "routeOnly": false },
  "allocate": { "strategy": "always", "refresh": 5, "concurrency": 3 }
}
```

--------------------------------

### Usage example: checkAlive function

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/observatory.md

Shows how to retrieve the observatory feature from a core instance and check the alive status of a specific outbound tag. It calls GetObservation, casts the result to ObservationResult, and iterates over the statuses to find the matching tag.

```go
import (
	"context"

	"github.com/xtls/xray-core/app/observatory"
	"github.com/xtls/xray-core/core"
	"github.com/xtls/xray-core/features/extension"
)

func checkAlive(v *core.Instance, tag string) (bool, error) {
	obs := v.GetFeature(extension.ObservatoryType())
	if obs == nil {
		return false, errors.New("no observatory feature")
	}
	msg, err := obs.(extension.Observatory).GetObservation(context.Background())
	if err != nil {
		return false, err
	}
	result := msg.(*observatory.ObservationResult)
	for _, st := range result.Status {
		if st.OutboundTag == tag {
			return st.Alive, nil
		}
	}
	return false, errors.New("tag not observed")
}
```

--------------------------------

### Usage example: storing and reading session context

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/session.md

Shows how to store session metadata in the context at the inbound handler entry and retrieve it later in the dispatcher. The first function builds an Inbound with Source and Tag, enables sniffing via Content, and sets an empty Outbound. The second reads the last outbound's Target, returning false if none exist.

```go
import (
	"context"

	"github.com/xtls/xray-core/common/net"
	"github.com/xtls/xray-core/common/session"
)

// inbound handler entry: build and store session metadata
func handleConnection(ctx context.Context, conn net.Conn, tag string) context.Context {
	remote := conn.RemoteAddr()
	ctx = session.ContextWithInbound(ctx, &session.Inbound{
		Source: net.DestinationFromAddr(remote),
		Tag:    tag,
	})
	ctx = session.ContextWithContent(ctx, &session.Content{
		SniffingRequest: session.SniffingRequest{Enabled: true},
	})
	ctx = session.ContextWithOutbounds(ctx, []*session.Outbound{{}})
	return ctx
}

// later, in the dispatcher:
func readTarget(ctx context.Context) (net.Destination, bool) {
	obs := session.OutboundsFromContext(ctx)
	if len(obs) > 0 {
		return obs[len(obs)-1].Target, true
	}
	return net.Destination{}, false
}
```

--------------------------------

### Route logs to a custom handler with log.RegisterHandler

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/errors-log.md

Use this to register a custom log handler that receives all log messages. The example defines a consoleLogger type implementing log.Handler, registers it, and records a message. After registration, all xerrors.Log* calls route to this handler until app/log.Instance replaces it.

```go
package main

import (
	"fmt"

	"github.com/xtls/xray-core/common/log"
)

type consoleLogger struct{}

func (consoleLogger) Handle(msg log.Message) {
	fmt.Println(msg.String())
}

func main() {
	log.RegisterHandler(consoleLogger{})
	log.Record(&log.GeneralMessage{Severity: log.Severity_Info, Content: "hello"})

	// After this, all xerrors.Log* calls across the process route here,
	// and app/log.Instance replaces this handler when it starts.
}
```

--------------------------------

### Init method signature

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/router.md

Initializes the Router with context, config, DNS client, outbound manager, and dispatcher. Returns an error from ReloadRules.

```go
// Init initializes the Router.
func (r *Router) Init(ctx context.Context, config *Config, d dns.Client, ohm outbound.Manager, dispatcher routing.Dispatcher) error
```

--------------------------------

### AddFeature

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

Registers a feature into current Instance. If the instance is running, the feature is started immediately instead — Start() errors are only logged (errors.LogInfoInner).

```APIDOC
## AddFeature

### Description
Registers a feature into current Instance. If the instance is running, the feature is started immediately instead — Start() errors are only logged (errors.LogInfoInner).

### Method
AddFeature

### Signature
func (s *Instance) AddFeature(feature features.Feature) error

### Parameters
- feature (features.Feature) - Required - The feature to register.

### Returns
- error - nil on success, or an error if registration fails.
```

--------------------------------

### Router.Init

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/router.md

Initializes the Router with the provided context, configuration, DNS client, outbound manager, and dispatcher.

```APIDOC
## Init

### Description
Initializes the Router with the provided context, configuration, DNS client, outbound manager, and dispatcher.

### Method
Init

### Signature
`func (r *Router) Init(ctx context.Context, config *Config, d dns.Client, ohm outbound.Manager, dispatcher routing.Dispatcher) error`

### Parameters
- **ctx** (`context.Context`) - Required - Instance context.
- **config** (`*Config`) - Required - Router config (rules, balancing rules, domain strategy, logging).
- **d** (`dns.Client`) - Required - DNS client for ipOnDemand/ipIfNonMatch strategies.
- **ohm** (`outbound.Manager`) - Required - Outbound manager for balancer selection.
- **dispatcher** (`routing.Dispatcher`) - Required - Dispatcher used by balancer rules.

### Returns
- **error** - from `ReloadRules`.
```

--------------------------------

### New(ctx context.Context, config *Config) (*DNS, error)

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/dns.md

Creates a new DNS server with the given configuration. It validates the configuration, sets up static hosts, name server clients, and query strategies, and returns the DNS instance or an error.

```APIDOC
## New(ctx context.Context, config *Config) (*DNS, error)

### Description
Creates a new DNS server with the given configuration. It validates the configuration, sets up static hosts, name server clients, and query strategies, and returns the DNS instance or an error.

### Method
Constructor function

### Signature
`func New(ctx context.Context, config *Config) (*DNS, error)`

### Parameters
- **ctx** (`context.Context`) - Required - Instance context.
- **config** (`*Config`) - Required - Configuration containing `ClientIp`, `QueryStrategy`, `StaticHosts`/hosts map, `NameServer` list, `DisableCache`, `ServeStale`, `ServeExpiredTTL`, `Tag`, `DisableFallback`, `DisableFallbackIfMatch`, `EnableParallelQuery`.

### Returns
- `(*DNS, error)` - The created DNS server instance and an error if any.

### Errors
- `"unexpected client IP length <n>"` - `ClientIp` not 0/4/16 bytes.
- `"unexpected query strategy <v>"` - unknown `QueryStrategy` value.
- `"failed to create hosts"` - hosts parsing failure.
- `"no QueryStrategy available for <address>"` - a nameserver with no enabled IP family.
- `"failed to create client"` - per-nameserver client creation failure.

### Query Strategies
- `USE_IP=0`
- `USE_IP4=1`
- `USE_IP6=2`
- `USE_SYS=3`

### Notes
If no clients are configured, a local (`/etc/resolv.conf`-backed) client is appended.
```

--------------------------------

### Observer.Start() error

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/observatory.md

Starts the background probing loop when SubjectSelector is non-empty.

```APIDOC
## Observer.Start() error

### Description
Starts the background probing loop that periodically probes selected outbounds and updates status.

### Method
Method

### Signature
`func (o *Observer) Start() error`

### Returns
- error - nil on success.
```

--------------------------------

### Build and dial a destination

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/net.md

Shows how to parse a destination string, build one programmatically, and dial it using core.Dial. Includes error handling for invalid host:port.

```go
package main

import (
	"context"
	"log"

	"github.com/xtls/xray-core/common/net"
	"github.com/xtls/xray-core/core"
)

func main() {
	// Parse a full destination string
	dest, err := net.ParseDestination("tcp:example.com:443")
	if err != nil {
		log.Fatal(err) // bad host:port
	}

	// Build one programmatically
	dest = net.TCPDestination(net.ParseAddress("1.1.1.1"), net.Port(853))

	instance, _ := core.StartInstance("protobuf", cfgBytes)
	conn, err := core.Dial(context.Background(), instance, dest)
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	// ...
}

```

--------------------------------

### SubscribeRunnableChannel

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/stats.md

Helper function that subscribes to a channel and automatically starts it when the first subscriber arrives.

```APIDOC
## SubscribeRunnableChannel

### Description
Subscribes to a channel and starts it if this is the first subscriber.

### Signature
func SubscribeRunnableChannel(c Channel) (chan interface{}, error)

```

--------------------------------

### New constructor for DNS server

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/dns.md

Creates a new DNS server with the given configuration. Returns an error for invalid client IP length, query strategy, hosts parsing, or client creation.

```go
// New creates a new DNS server with given configuration.
func New(ctx context.Context, config *Config) (*DNS, error)
```

--------------------------------

### NewWithContext(ctx context.Context, config *Config) (*Instance, error)

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/core-instance.md

Creates a new Xray instance with a caller-provided context as the base context. Same contract as New, but uses the given context instead of context.Background().

```APIDOC
## NewWithContext(ctx context.Context, config *Config) (*Instance, error)

### Description
Creates a new Xray instance based on the provided configuration, using the caller-provided context as the base context of the instance. The instance is not started at this point. The config must contain one Dispatcher, one InboundHandlerManager, and one OutboundHandlerManager for proper operation.

### Method
Constructor

### Signature
```go
func NewWithContext(ctx context.Context, config *Config) (*Instance, error)
```

### Parameters
- **ctx** (`context.Context`) - Required - The base context for the instance, used instead of context.Background().
- **config** (`*Config`) - Required - Master Xray configuration. Must contain at least one inbound and one outbound handler config per the protobuf definition, plus apps for Dispatcher, InboundManager, and OutboundManager for a functional instance.

### Returns
- **(*Instance, error)** - A fully constructed but not started instance. The error is non-nil when config parsing of embedded TypedMessage app settings fails, when a config type is not registered with common.RegisterConfig, when not all required dependencies are resolved, or when inbound/outbound handler creation fails.

### Behavior Notes
Same construction behavior as New, but uses the provided context as the base context.
```

--------------------------------

### OutboundDetourConfig JSON example

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/infra-conf.md

JSON configuration for an outbound detour. The `mux` section maps directly to `proxyman.MultiplexingConfig`.

```json
{
  "tag": "proxy",
  "protocol": "vless",
  "settings": { "vnext": [ { "address": "example.com", "port": 443, "users": [ { "id": "...", "encryption": "none" } ] } ] },
  "streamSettings": { "network": "tcp", "security": "reality", "realitySettings": { ... } },
  "mux": { "enabled": true, "concurrency": 8, "xudpConcurrency": 8, "xudpProxyUDP443": "reject" },
  "proxySettings": { "tag": "another-outbound" }
}
```

--------------------------------

### Create inbound and outbound config loaders

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/infra-conf.md

Creates the inbound and outbound config loaders with the protocol key and settings key, listing supported protocols.

```go
inboundConfigLoader = NewJSONConfigLoader(ConfigCreatorCache{ ... }, "protocol", "settings")
// protocols: tunnel|dokodemo-door, http, shadowsocks, mixed|socks, vless, vmess, trojan, wireguard, hysteria, masque, tun

outboundConfigLoader = NewJSONConfigLoader(ConfigCreatorCache{ ... }, "protocol", "settings")
// protocols: block|blackhole, loopback, direct|freedom, http, shadowsocks, socks, vless, vmess, trojan, hysteria, masque, dns, wireguard
```

--------------------------------

### Counter

Source: https://github.com/xtls/xray-core/blob/main/_autodocs/api-reference/stats.md

The Counter type provides an atomic integer counter with methods to get, set, and add values.

```APIDOC
## Counter

### Description
An atomic int64 counter used for statistics.

### Methods

#### Value() int64
Returns the current value of the counter.

#### Set(v int64) int64
Sets the counter to a new value and returns the previous value.

#### Add(v int64) int64
Adds a value to the counter and returns the previous value.

```
Tokens:
Raw