Surgio Documentation

The examples in this repository are designed to demonstrate how to use specific, independent features of Surgio. They are not intended to represent a complete, ready-to-use rule repository.

If you are looking for a complete, out-of-the-box rule repository setup, please refer to the Getting Started guide.

Surgio is a tool designed to automate the creation of proxy configuration files for different clients. It solves the problem of managing multiple proxy subscriptions (from different providers) and multiple proxy clients (which often require different configuration formats) by providing a unified workflow.

Core Workflow

Surgio operates in two main stages:

1. Parsing: It parses subscription URLs from various providers or parses your own maintained node lists (supporting protocols like Shadowsocks, Vmess, and Shadowsocksr).
2. Generation: It uses templates to define rules and generates specific configuration files tailored for different proxy clients.

Additionally, Surgio includes a utility to upload generated configurations to Alibaba Cloud OSS, enabling you to quickly create subscription links for your clients.

In asynchronous mode, nodeList is a function that receives customParams. This allows you to generate dynamic node lists based on request parameters.

If you are using Gateway, customParams includes all parameters from the request URL. Note that all URL parameters are provided as strings (e.g., mobile=true results in customParams.mobile === 'true'). The requestUserAgent is also included by default to help differentiate lists based on the client.

const { defineCustomProvider } = require('surgio')

module.exports = defineCustomProvider({
  nodeList: async (customParams) => {
    if (customParams.mobile === 'true') {
      return [
        {
          type: 'shadowsocks',
          // ...
        },
      ]
    } else {
      return [
        {
          type: 'trojan',
          // ...
        },
      ]
    }
  },
})

For sing-box, nodes are handled differently depending on their type:

1. Outbounds: Use getSingboxNodes(nodeList, filter?) to get an array of node information for outbound rules.
2. Endpoints: sing-box treats Tailscale nodes as endpoints. Use getSingboxEndpoints(nodeList, filter?) to get an array of endpoint information for the endpoints field in the configuration.
3. Node Names: Use getSingboxNodeNames(nodeList, filter?) to get an array of names that includes both outbounds and endpoints, making them easy to reference in selector or urltest blocks.

Example for node names:

getSingboxNodeNames(nodeList, netflixFilter);

If you are using an API gateway and have multiple subscriptions or remote fragments, enabling Redis cache can significantly reduce cold start times.

Standard local caching in Surgio uses files and memory. However, these are cleared whenever a Serverless platform is redeployed or when a process is suspended, leading to longer cold starts. Because Redis runs in an independent process, it persists across these events, maintaining cache availability.

Surgio uses Artifact objects to determine how configuration files are generated. You can define multiple Artifacts to generate various configuration files in a single run. An Artifact requires a name, a template, and a provider.

{
  name: 'SurgeV3.conf',
  template: 'surge_v3',
  provider: 'demo',
}

Filters allow you to narrow down the nodeList to specific nodes based on criteria like location, protocol, or service support. Most built-in functions like getSurgeNodes accept a filter as the second argument.

To use a custom filter, access it via the customFilters object.

When writing an asynchronous nodeList function in a custom Provider, you can access metadata about the incoming subscription request via the customParams argument. This allows you to dynamically change the returned nodes based on who is requesting them.

Key properties available in customParams:

• requestUserAgent: The UserAgent string of the client making the request.
• [key]: Any URL query parameters passed in the request URL (all values are strings). For example, if the URL is ?game=1, you can access it via customParams.game.

Surgio uses Nunjucks for flexible template definitions. The filename of the template serves as its name, which is used when defining an Artifact. Variables within the template are accessed using the {{ variableName }} syntax.

To use custom parameters defined in an Artifact, access them via the customParams object.

Surgio operates on three core abstractions to transform node data into usable configurations:

• Provider: The source of nodes. This can be a subscription URL or a set of node configurations.
• Template: The logic used by Surgio to render specific files based on the provided data.
• Artifact: The final output or "product" generated by Surgio (the resulting rules/configurations).

Relationship: Surgio takes nodes from a Provider and uses a Template to generate an Artifact.

When configuring proxy rules for Apple services, it is strongly recommended to use the built-in apple_rules.tpl template. This template is designed to effectively handle traffic splitting for both Apple service interfaces and Apple's global CDN.

Note: While you can reference other remote snippets, Surgio specifically supports referencing Surge remote snippets.