docs: add more examples

docs/.vuepress/theme/index.ts

@@ -35,7 +35,7 @@ export default {
           },
           {
             text: '客户端规则维护指南',
-            children: ['/guide/client/clash'],
+            children: ['/guide/client/clash', '/guide/client/examples'],
           },
           '/guide/api',
           '/guide/cli',

docs/guide/client/examples.md

@@ -0,0 +1,26 @@
+---
+title: 代码示例
+sidebarDepth: 2
+---
+
+# 代码示例
+
+这些案例引用了我维护的代理规则，你也可以用相似的方法引用其它的远程片段。需要注意的是，我们只能引用 Surge 的远程片段。
+
+对于 `Apple` 和 `Apple CDN` 这两个策略组，我强烈建议你使用内置的 `apple_rules.tpl`，它可以很好的解决苹果服务接口的访问和苹果全球 CDN 的访问分流。想了解更多细节可以阅读 [这篇文章](https://royli.dev/blog/2019/better-proxy-rules-for-apple-services)。
+
+## Quantumult X + 远程规则
+
+对于 QuantumultX 来说，根据国别来生成托管文件是一个比较好的管理方式。
+
+在使用本仓库之前，你需要配置好阿里云 OSS 或者 Surgio 面板，这样才能让 QuantumultX 下载到托管文件。
+
+[仓库](https://github.com/surgioproject/surgio/tree/master/examples/quantumultx)
+
+## Clash + 远程规则
+
+[仓库](https://github.com/surgioproject/surgio/tree/master/examples/clash-remote-snippet)
+
+## 钩子函数
+
+[仓库](https://github.com/surgioproject/surgio/tree/master/examples/hooks)

examples/clash-remote-snippet/README.md

@@ -1,7 +1 @@
 # Example - Clash
-
-该样例生成的规则可以用于所有的 Clash 客户端。
-
-在这个案例中，引用了 [神机规则](https://github.com/ConnersHua/Profiles/tree/master/Surge)，你也可以用相似的方法引用其它的远程片段。需要注意的是，我们只能引用 Surge 的远程片段，而非 QuantumultX 的规则。
-
-对于 `Apple` 和 `Apple CDN` 这两个策略组，我强烈建议你使用内置的 `apple_rules.tpl`，它可以很好的解决苹果服务接口的访问和苹果全球 CDN 的访问分流。想了解更多细节可以阅读 [这篇文章](https://blog.dada.li/2019/better-proxy-rules-for-apple-services)。

examples/clash-remote-snippet/surgio.conf.js

@@ -4,15 +4,15 @@ module.exports = {
   remoteSnippets: [
     {
       name: 'youtube',
-      url: 'https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Ruleset/Media/YouTube.list',
+      url: 'https://raw.githubusercontent.com/geekdada/surge-list/master/youtube.list',
     },
     {
       name: 'global',
-      url: 'https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Ruleset/Global.list',
+      url: 'https://git.royli.dev/me/lhie1_Rules/raw/branch/master/Surge/Surge%203/Provider/Proxy.list',
     },
     {
       name: 'netflix',
-      url: 'https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Ruleset/Media/Netflix.list',
+      url: 'https://git.royli.dev/me/lhie1_Rules/raw/branch/master/Surge/Surge%203/Provider/Media/Netflix.list',
     },
   ],
   artifacts: [

examples/clash-remote-snippet/template/clash.tpl

@@ -25,7 +25,7 @@ Proxy Group:
   proxies: {{ getClashNodeNames(nodeList, netflixFilter) | json }}
 - type: select
   name: 📺 Youtube
-  proxies: {{ getClashNodeNames(nodeList, youtubeFilter) | json }}
+  proxies: {{ getClashNodeNames(nodeList) | json }}
 - type: url-test
   name: US
   proxies: {{ getClashNodeNames(nodeList, usFilter) | json }}
@@ -44,9 +44,11 @@ Proxy Group:
   proxies: ['DIRECT', '🍎 Apple']
 
 Rule:
-{{ remoteSnippets.netflix.main('🎬 Netflix') | patchYamlArray }}
-{{ remoteSnippets.youtube.main('📺 Youtube') | patchYamlArray }}
-{{ remoteSnippets.global.main('🚀 Proxy') | patchYamlArray }}
+{% filter clash %}
+{{ remoteSnippets.netflix.main('🎬 Netflix') }}
+{{ remoteSnippets.youtube.main('📺 Youtube') }}
+{{ remoteSnippets.global.main('🚀 Proxy') }}
+{% endfilter %}
 
 # LAN
 - DOMAIN-SUFFIX,local,DIRECT

examples/hooks/README.md

@@ -0,0 +1 @@
+# Example - Clash

examples/hooks/provider/demo.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const { defineClashProvider } = require('surgio')
+
+/**
+ * 这是一个能够成功的实例，它会从远程获取 Clash 配置
+ */
+module.exports = defineClashProvider({
+  url: 'https://raw.githubusercontent.com/surgioproject/surgio/master/test/asset/clash-sample.yaml',
+  type: 'clash',
+  udpRelay: true,
+  addFlag: true,
+  hooks: {
+    afterNodeListResponse: async (nodeList, customParams) => {
+      if (customParams.requestUserAgent?.toLowerCase().includes('surge')) {
+        // 假如是 Surge 请求则在末尾插入一个我自己维护的节点
+        nodeList.push({
+          type: 'shadowsocks',
+          nodeName: 'US 自定义节点',
+          hostname: 'example.com',
+          port: 8388,
+          method: 'chacha20-ietf-poly1305',
+          password: 'password',
+        })
+      }
+
+      return nodeList
+    },
+  },
+})

examples/hooks/provider/error.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const { defineClashProvider } = require('surgio')
+
+/**
+ * 这是一个一定会失败的示例
+ */
+module.exports = defineClashProvider({
+  url: 'https://raw.githubusercontent.com/surgioproject/surgio/master/test/asset/not-exist.yaml',
+  type: 'clash',
+  udpRelay: true,
+  addFlag: true,
+  hooks: {
+    onError: async () => {
+      return [
+        {
+          nodeName: 'Fallback',
+          type: 'shadowsocks',
+          hostname: 'fallback.example.com',
+          port: 443,
+          method: 'chacha20-ietf-poly1305',
+          password: 'password',
+        },
+      ]
+    },
+  },
+})

examples/hooks/surgio.conf.js

@@ -0,0 +1,31 @@
+'use strict'
+
+const { defineSurgioConfig } = require('surgio')
+
+module.exports = defineSurgioConfig({
+  remoteSnippets: [
+    {
+      name: 'youtube',
+      url: 'https://raw.githubusercontent.com/geekdada/surge-list/master/youtube.list',
+    },
+    {
+      name: 'global',
+      url: 'https://git.royli.dev/me/lhie1_Rules/raw/branch/master/Surge/Surge%203/Provider/Proxy.list',
+    },
+    {
+      name: 'netflix',
+      url: 'https://git.royli.dev/me/lhie1_Rules/raw/branch/master/Surge/Surge%203/Provider/Media/Netflix.list',
+    },
+  ],
+  artifacts: [
+    {
+      name: 'Clash.yaml',
+      template: 'clash',
+      provider: 'demo',
+      combineProviders: ['error'],
+    },
+  ],
+  urlBase: 'https://config.example.com/',
+  // https://surgio.js.org/guide/custom-config.html#upload
+  // upload: {},
+})

examples/hooks/template/clash.tpl

@@ -0,0 +1,64 @@
+allow-lan: true
+mode: Rule
+external-controller: 127.0.0.1:7892
+port: 7890
+socks-port: 7891
+{% if customParams.enhancedMode %}
+dns:
+  enable: true
+  ipv6: false
+  listen: 0.0.0.0:53
+  enhanced-mode: fake-ip
+  nameserver:
+  - 119.29.29.29
+  - 223.5.5.5
+{% endif %}
+
+Proxy: {{ getClashNodes(nodeList) | json }}
+
+Proxy Group:
+- type: select
+  name: 🚀 Proxy
+  proxies: {{ getClashNodeNames(nodeList) | json }}
+- type: select
+  name: 🎬 Netflix
+  proxies: {{ getClashNodeNames(nodeList, netflixFilter) | json }}
+- type: select
+  name: 📺 Youtube
+  proxies: {{ getClashNodeNames(nodeList) | json }}
+- type: url-test
+  name: US
+  proxies: {{ getClashNodeNames(nodeList, usFilter) | json }}
+  url: {{ proxyTestUrl }}
+  interval: 1200
+- type: url-test
+  name: HK
+  proxies: {{ getClashNodeNames(nodeList, hkFilter) | json }}
+  url: {{ proxyTestUrl }}
+  interval: 1200
+- type: select
+  name: 🍎 Apple
+  proxies: ['DIRECT', '🚀 Proxy', 'US', 'HK']
+- type: select
+  name: 🍎 Apple CDN
+  proxies: ['DIRECT', '🍎 Apple']
+
+Rule:
+{% filter clash %}
+{{ remoteSnippets.netflix.main('🎬 Netflix') }}
+{{ remoteSnippets.youtube.main('📺 Youtube') }}
+{{ remoteSnippets.global.main('🚀 Proxy') }}
+{% endfilter %}
+
+# LAN
+- DOMAIN-SUFFIX,local,DIRECT
+- IP-CIDR,127.0.0.0/8,DIRECT
+- IP-CIDR,172.16.0.0/12,DIRECT
+- IP-CIDR,192.168.0.0/16,DIRECT
+- IP-CIDR,10.0.0.0/8,DIRECT
+- IP-CIDR,17.0.0.0/8,DIRECT
+- IP-CIDR,100.64.0.0/10,DIRECT
+
+# Final
+- GEOIP,CN,DIRECT
+- MATCH,🚀 Proxy

examples/quantumultx/README.md

@@ -1,9 +1 @@
 # Example - QuantumultX
-
-对于 QuantumultX 来说，根据国别来生成托管文件是一个比较好的管理方式。
-
-在使用本仓库之前，你需要配置好阿里云 OSS，这样才能让 QuantumultX 下载到托管文件。
-
-在这个案例中，引用了 [神机规则](https://github.com/ConnersHua/Profiles/tree/master/Surge)，你也可以用相似的方法引用其它的远程片段。需要注意的是，我们只能引用 Surge 的远程片段，而非 QuantumultX 的规则。
-
-对于 `Apple` 和 `Apple CDN` 这两个策略组，我强烈建议你使用内置的 `apple_rules.tpl`，它可以很好的解决苹果服务接口的访问和苹果全球 CDN 的访问分流。想了解更多细节可以阅读 [这篇文章](https://blog.dada.li/2019/better-proxy-rules-for-apple-services)。

examples/quantumultx/surgio.conf.js

@@ -6,15 +6,15 @@ module.exports = {
   remoteSnippets: [
     {
       name: 'youtube',
-      url: 'https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Ruleset/Media/YouTube.list',
+      url: 'https://raw.githubusercontent.com/geekdada/surge-list/master/youtube.list',
     },
     {
       name: 'global',
-      url: 'https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Ruleset/Global.list',
+      url: 'https://git.royli.dev/me/lhie1_Rules/raw/branch/master/Surge/Surge%203/Provider/Proxy.list',
     },
     {
       name: 'netflix',
-      url: 'https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Ruleset/Media/Netflix.list',
+      url: 'https://git.royli.dev/me/lhie1_Rules/raw/branch/master/Surge/Surge%203/Provider/Media/Netflix.list',
     },
   ],
   artifacts: [

package.json

@@ -40,6 +40,7 @@
     "test:lint": "eslint -c .eslintrc.js --ext .js,.ts .",
     "test:unit": "ava",
     "test:cli": "mocha",
+    "run-example": "node ./scripts/run-example.js",
     "coverage": "TS_NODE_FILES=true nyc ava",
     "clean": "rimraf build",
     "build": "tsc -p tsconfig.build.json",

scripts/run-example.js

@@ -0,0 +1,22 @@
+'use strict'
+
+const execa = require('execa')
+const { resolve } = require('path')
+const fs = require('fs-extra')
+
+const { argv } = process
+const [, , example] = argv
+
+if (!example) {
+  console.error('Please provide an example name')
+  process.exit(1)
+}
+
+const binPath = resolve(__dirname, '..', 'bin/run')
+const examplePath = resolve(__dirname, '..', 'examples', example)
+const nodeModulesPath = resolve(examplePath, 'node_modules')
+
+fs.ensureDirSync(nodeModulesPath)
+fs.ensureSymlinkSync(process.cwd(), resolve(nodeModulesPath, 'surgio'))
+
+execa(binPath, ['generate', '--project', examplePath], { stdio: 'inherit' })