doc: improve consistency

Signed-off-by: He Xian <hexian000@outlook.com>
hexian000 · Nov 10, 2024 · 1076d98 · 1076d98
1 parent 61eca00
commit 1076d98
Show file tree

Hide file tree

Showing 5 changed files with 31 additions and 28 deletions.
diff --git a/API.md b/API.md
@@ -60,7 +60,7 @@ Load the posted script and use it as follows:
 3. If the field `_G.name` refers to the named module, it will be updated too.
 
 - **Path**: `/ruleset/update`
-- **Query**: `?module=name&chunkname=name.lua` (optional)
+- **Query**: `?module=name&chunkname=%40name.lua` (optional)
 - **Method**: POST
 - **Content**: Lua ruleset script or Lua module script
 - **Status**: HTTP 200, HTTP 500
@@ -172,7 +172,7 @@ end
 
 **Description**
 
-Periodic timer callback.
+Periodic timer callback. See [neosocksd.setinterval](#neosocksdsetinterval).
 
 **Params**
 
@@ -251,7 +251,7 @@ local host, port = neosocksd.splithostport("example.com:80")
 
 **Description**
 
-Split address string into host and port. Raises error on failure.
+Split address string into host and port. Raises an error on failure.
 
 
 ### neosocksd.parse_ipv4
@@ -301,7 +301,7 @@ neosocksd.setinterval(1.5)
 
 **Description**
 
-Set tick interval in seconds, see also [ruleset.tick](#rulesettick).
+Set the interval to call [ruleset.tick](#rulesettick) in seconds.
 
 The valid interval range is `[1e-3, 1e+9]`, use `setinterval(0)` to stop the timer tick.
 
@@ -455,7 +455,7 @@ end)
 
 **Description**
 
-Resolves a host name asynchronously. If asynchronous name resolution is not configured, `await.resolve` behaves the same as `neosocksd.resolve`.
+Resolves a host name asynchronously. If asynchronous name resolution is not supported, `await.resolve` behaves the same as `neosocksd.resolve`.
 
 IPv4/IPv6 preference depends on command line argument `-4`/`-6`.
 

diff --git a/agent.lua b/agent.lua
@@ -5,6 +5,7 @@
 _G.libruleset = require("libruleset")
 
 local agent = {}
+agent.running = true
 
 -- agent.peername = "peer0"
 agent.peername = table.get(_G.agent, "peername")
@@ -380,7 +381,6 @@ local function main(...)
             evlogf("agent.stop: %s", err)
         end
     end
-    agent.running = true
     async(mainloop)
     return agent
 end

diff --git a/example/gen_biglist.lua b/example/gen_biglist.lua
@@ -136,9 +136,9 @@ function main(args)
     local cidr6 = parse_cidr(args[2])
     local domain, host, regex = parse_list(args[3])
     local f = io.stdout
-    f:write(string.format("_G.biglist4=inet.subnet(%s)\n", marshal(cidr)))
+    f:write(string.format("_G.biglist=inet.subnet(%s)\n", marshal(cidr)))
     f:write(string.format("_G.biglist6=inet6.subnet(%s)\n", marshal(cidr6)))
-    f:write(string.format("_G.biglist=composite.anyof({match.domaintree(%s),match.host(%s),match.regex(%s)})\n",
+    f:write(string.format("_G.biglist_name=composite.anyof({match.domaintree(%s),match.host(%s),match.regex(%s)})\n",
         marshal(domain), marshal(host), marshal(regex)))
     f:close()
     return 0

diff --git a/example/ruleset.lua b/example/ruleset.lua
@@ -38,20 +38,20 @@ local INTERNAL_DOMAIN = ".internal"
 -- _G.redirect_name: for requests with name string
 _G.redirect_name = {
     -- rule.redirect(addr, proxy1, proxy2, ...)
-    { match.exact("peer0.lan:22"),        rule.redirect("host-gateway:22"),       "ssh" },
-    { match.exact("peer0.lan:80"),        rule.redirect("nginx:80"),              "web" },
-    { match.exact("peer0.lan:443"),       rule.redirect("nginx:443"),             "web" },
+    { match.exact("peer0.lan:22"),         rule.redirect("host-gateway:22"),       "ssh" },
+    { match.exact("peer0.lan:80"),         rule.redirect("nginx:80"),              "web" },
+    { match.exact("peer0.lan:443"),        rule.redirect("nginx:443"),             "web" },
     -- access local sites directly
-    { match.domain({ ".lan", ".local" }), rule.direct(),                          "lan" },
+    { match.domain({ ".lan", ".local" }),  rule.direct(),                          "lan" },
     -- ".internal" assignment
-    { match.exact(API_ENDPOINT),          rule.redirect("127.0.1.1:9080") },
-    { match.agent(),                      rule.agent() }, -- agent relay
-    { match.exact("peer0.internal:22"),   rule.redirect("host-gateway:22"),       "ssh" },
-    { match.domain(INTERNAL_DOMAIN),      rule.reject(),                          "unknown" },
+    { match.exact(API_ENDPOINT),           rule.redirect("127.0.1.1:9080") },
+    { match.agent(),                       rule.agent() }, -- agent relay
+    { match.exact("peer0.internal:22"),    rule.redirect("host-gateway:22"),       "ssh" },
+    { match.domain(INTERNAL_DOMAIN),       rule.reject(),                          "unknown" },
     -- global condition
-    { is_disabled,                        rule.reject(),                          "off" },
+    { is_disabled,                         rule.reject(),                          "off" },
     -- dynamically loaded big domains list, rule.proxy(proxy1, proxy2, ...)
-    { composite.maybe(_G, "biglist"),     rule.proxy("socks4a://proxy.lan:1080"), "biglist" },
+    { composite.maybe(_G, "biglist_name"), rule.proxy("socks4a://proxy.lan:1080"), "biglist" },
     -- if in _G.hosts, go to _G.route/_G.route6
     -- otherwise, go to _G.route_default
 }
@@ -81,19 +81,22 @@ _G.hosts = {
     ["host123.region2.lan"] = "192.168.33.123"
 }
 
+-- jump to region2 through region1 proxy
+local proxy_region2 = rule.proxy("socks4a://192.168.32.1:1080", "socks4a://192.168.33.1:1080")
+
 -- 3. _G.route*: match the IP address
 _G.route = {
     -- reject loopback or link-local
-    { inet.subnet("127.0.0.0/8"),      rule.reject() },
-    { inet.subnet("169.254.0.0/16"),   rule.reject() },
+    { inet.subnet("127.0.0.0/8"),     rule.reject() },
+    { inet.subnet("169.254.0.0/16"),  rule.reject() },
     -- region1 proxy
-    { inet.subnet("192.168.32.0/24"),  rule.proxy("socks4a://192.168.32.1:1080"),                                "region1" },
-    -- jump to region2 through region1 proxy (for a fancy demo)
-    { inet.subnet("192.168.33.0/24"),  rule.proxy("socks4a://192.168.32.1:1080", "socks4a://192.168.33.1:1080"), "region2" },
+    { inet.subnet("192.168.32.0/24"), rule.proxy("socks4a://192.168.32.1:1080"), "region1" },
+    -- region2 proxy
+    { inet.subnet("192.168.33.0/24"), proxy_region2,                             "region2" },
     -- access other lan addresses directly
-    { inet.subnet("192.168.0.0/16"),   rule.direct(),                                                            "lan" },
+    { inet.subnet("192.168.0.0/16"),  rule.direct(),                             "lan" },
     -- dynamically loaded big IP ranges list
-    { composite.maybe(_G, "biglist4"), rule.direct(),                                                            "biglist" },
+    { composite.maybe(_G, "biglist"), rule.direct(),                             "biglist" },
     -- go to _G.route_default
 }
 
@@ -108,9 +111,9 @@ _G.route6 = {
     -- go to _G.route_default
 }
 
--- 4. the global default applies to any unmatched requests
+-- 4. the global default applies to all unmatched requests
 -- in {action, optional log tag}
-_G.route_default = { rule.proxy("socks5://user:pass@internet-gateway.lan:1080"), "internet" }
+_G.route_default = { rule.proxy("socks5://user:pass@gateway.lan:1080"), "wan" }
 
 function ruleset.stats(dt, q)
     local w = list:new()

diff --git a/example/ruleset_simple.lua b/example/ruleset_simple.lua
@@ -58,7 +58,7 @@ _G.route6        = {
     -- go to _G.route_default
 }
 
--- 4. the global default applies to any unmatched requests
+-- 4. the global default applies to all unmatched requests
 -- in {action, optional log tag}
 _G.route_default = { rule.proxy("socks5://user:pass@internet-gateway.lan:1080"), "internet" }