radiance

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2025 License: GPL-3.0 Imports: 25 Imported by: 0

README

Go

Radiance

Radiance is the backend core of the Lantern client that integrates sing-box and the Outline SDK in addition to Lantern's own protocols and techniques. This is still under development and is not ready or even functional for production use.

See Lantern client for build instructions.

What's the "core" idea behind a lantern? Light, or synonymously, radiance.

What's it do?

radiance runs a TUN device on the user's device via sing-tun and integrates all sing-box protocols (shadowsocks, hysteria2, vmess, anytls, etc) in addition to a proxyless dialer from the Outline SDK and AmneziaWG. Radiance also integrates application layer Geneva, compatibility with WATER/WASM-based transports, and a continuous stream of new Lantern protocols and approaches to stayin unblocked.

Interoperability

Interoperability is at the core of Lantern and Radiance. Lantern is designed to interoperate with everything from Outline servers to sing-box servers to servers running Lantern's own sing-box extensions. You can similarly run Lantern servers to interoperate with any of those clients. The addition of WATER means that Lantern can deliver new protocols written in any WASM-compatible language at runtime without client-side updates.

Environment Variables

Configuration can be controlled by setting environment variables or creating a .env file in the same directory as the compiled executable or project root directory if running the souce directly. The order of precedence for setting these is as follows:

  1. Environment variables (highest precedence)
  2. .env file (lowest precedence)

Available variables:

  • RADIANCE_LOG_LEVEL: Sets the log level (e.g., trace, debug, info, warn, error, fatal).
  • RADIANCE_LOG_PATH: Sets the absolute path to the log file.
  • RADIANCE_DATA_PATH: Sets the absolute path to the data directory.
  • RADIANCE_DISABLE_FETCH_CONFIG: If set to true, disables fetching the remote config.
  • RADIANCE_DISABLE_STDOUT_LOG: Disable printing radiance logs to STDOUT. Logs will still be written to the log file.

Packages

Use common.Init to setup directories and configure loggers.

[!note] This isn't necessary if NewRadiance was called as it will call Init for you.

vpn

The vpn package provides high-level functions for controlling the VPN tunnel.

To connect to the best available server, you can use the QuickConnect function. This function takes a server group (servers.SGLantern, servers.SGUser, or "all") and a PlatformInterface as input. For example:

err := vpn.QuickConnect(servers.SGLantern, platIfce)

will connect to the best Lantern server, while:

err := vpn.QuickConnect("all", platIfce)

will connect to the best overall.

You can also connect to a specific server using ConnectToServer. This function requires a server group, a server tag, and a PlatformInterface. For example:

err := vpn.ConnectToServer(servers.SGUser, "my-server", platIfce)

Both QuickConnect and ConnectToServer can be called without disconnecting first, allowing you to seamlessly switch between servers or connection modes.

Once connected, you can check the GetStatus or view ActiveConnections. To stop the VPN, simply call Disconnect. The package also supports reconnecting to the last used server with Reconnect.

This package also includes split tunneling capabilities, allowing you to include or exclude specific applications, domains, or IP addresses from the VPN tunnel. You can manage split tunneling by creating a SplitTunnel handler with NewSplitTunnelHandler. This handler allows you to Enable or Disable split tunneling, AddItem or RemoveItem from the filter, and view the current Filters.

servers

The servers package is responsible for managing all VPN server configurations, separating them into two groups: lantern (official Lantern servers) and user (user-provided servers).

The Manager allows you to AddServers and RemoveServer configurations. You can retrieve the config for a specific server with GetServerByTag or use Servers to retrieve all configs.

[!caution] While you can get a new Manager instance with NewManager, it is recommended to use Radiance.ServerManager. This will return the shared manager instance. NewManager can be useful for retrieving server information if you don't have access to the shared instance, but the new instance should not be kept as it won't stay in sync and adding server configs to it will overwrite existing configs if both manager instances are pointed to the same server file.

A key feature of this package is the ability to add private servers from a server manager via an access token using AddPrivateServer. This process uses Trust-on-first-use (TOFU) to securely add the server. Once a private server is added, you can use the manager to invite other users to it with InviteToPrivateServer and revoke access with RevokePrivateServerInvite.

Documentation

Overview

Package radiance provides a local server that proxies all requests to a remote proxy server using different protocols meant to circumvent censorship. Radiance uses a [transport.StreamDialer] to dial the target server over the desired protocol. The config.Config is used to configure the dialer for a proxy server.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type IssueReport 

type IssueReport = issue.IssueReport

type Options 

type Options struct {
	DataDir  string
	LogDir   string
	Locale   string
	DeviceID string
	LogLevel string
}

type Radiance 

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

Radiance is a local server that proxies all requests to a remote proxy server over a transport.StreamDialer.

func NewRadiance 

func NewRadiance(opts Options) (*Radiance, error)

NewRadiance creates a new Radiance VPN client. opts includes the platform interface used to interact with the underlying platform on iOS, Android, and MacOS. On other platforms, it is ignored and can be nil.

func (*Radiance) APIHandler 

func (r *Radiance) APIHandler() *api.APIClient

APIHandler returns the API handler for the Radiance client.

func (*Radiance) AddConfigListener deprecated 

func (r *Radiance) AddConfigListener(onChange func())

AddConfigListener adds a listener that is called whenever the configuration changes.

Deprecated: Use events handler subscriptions instead.

func (*Radiance) Close 

func (r *Radiance) Close()

func (*Radiance) Features 

func (r *Radiance) Features() map[string]bool

Features returns the features available in the current configuration, returned from the server in the config response.

func (*Radiance) ReportIssue 

func (r *Radiance) ReportIssue(email string, report IssueReport) error

ReportIssue submits an issue report to the back-end with an optional user email

func (*Radiance) ServerLocations 

func (r *Radiance) ServerLocations() ([]lcommon.ServerLocation, error)

ServerLocations returns the list of server locations where the user can connect to proxies.

func (*Radiance) ServerManager 

func (r *Radiance) ServerManager() *servers.Manager

ServerManager returns the server manager for the Radiance client.

func (*Radiance) SetPreferredServer 

func (r *Radiance) SetPreferredServer(ctx context.Context, country, city string)

SetPreferredServer sets the preferred server location for the VPN connection. pass empty strings to auto select the server location

func (*Radiance) UserInfo 

func (r *Radiance) UserInfo() common.UserInfo

UserInfo returns the user info object for this client This is the user config object that contains the device ID and other user data

Source Files

View all Source files

Directories

Path Synopsis
api
protos
Package common contains common initialization code and utilities for the Radiance application.
 Package common contains common initialization code and utilities for the Radiance application.
atomicfile
Package atomicfile provides functions to read and write files atomically.
 Package atomicfile provides functions to read and write files atomically.
deviceid
env
Package env is responsible for loading radiance configuration based on a order of precedence (environment variables > configurations set at .env file).
 Package env is responsible for loading radiance configuration based on a order of precedence (environment variables > configurations set at .env file).
reporting
Package config provides a handler for fetching and storing proxy configurations.
 Package config provides a handler for fetching and storing proxy configurations.
Package events provides a simple publish-subscribe mechanism for event handling.
 Package events provides a simple publish-subscribe mechanism for event handling.
Package servers provides management of server configurations, such as option.Endpoints and option.Outbounds,and integration with remote server managers for adding, inviting, and revoking private servers with trust-on-first-use (TOFU) fingerprint verification.
 Package servers provides management of server configurations, such as option.Endpoints and option.Outbounds,and integration with remote server managers for adding, inviting, and revoking private servers with trust-on-first-use (TOFU) fingerprint verification.
Package telemetry provides OpenTelemetry setup for radiance
 Package telemetry provides OpenTelemetry setup for radiance
Package traces provides utilities for working with OpenTelemetry traces.
 Package traces provides utilities for working with OpenTelemetry traces.
vpn
Package vpn provides high-level management of VPN tunnels, including connecting to the best available server, connecting to specific servers, disconnecting, reconnecting, and querying tunnel status.
 Package vpn provides high-level management of VPN tunnels, including connecting to the best available server, connecting to specific servers, disconnecting, reconnecting, and querying tunnel status.
ipc
Package ipc implements the IPC server for communicating between the client and the VPN service.
 Package ipc implements the IPC server for communicating between the client and the VPN service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.