docs: align en/zh API docs with runtime interfaces

docs/src/en/guides/http-best-practices.md

@@ -724,6 +724,7 @@ Use `pcall` to catch exceptions, avoiding service crashes from individual reques
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local json = require "silly.encoding.json"
 
 -- Global error handler
@@ -1033,6 +1034,7 @@ Implement a middleware system for cross-cutting concerns (logging, authenticatio
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 -- Middleware chain
 local function chain(middlewares, final_handler)
@@ -1142,6 +1144,7 @@ Record detailed information for each request for audit and troubleshooting.
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local json = require "silly.encoding.json"
 
 local function access_log(stream, status, duration, response_size)
@@ -1294,17 +1297,18 @@ Use Trace ID to track request flow through the system.
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 http.listen {
     addr = ":8080",
     handler = function(stream)
         -- Get or generate Trace ID from request header
         local trace_id = tonumber(stream.header["x-trace-id"])
         if trace_id then
-            silly.traceset(trace_id)
+            trace.attach(trace_id)
         else
-            silly.tracespawn()
-            trace_id = silly.tracepropagate()  -- For returning to client
+            trace.spawn()
+            trace_id = trace.propagate()  -- For returning to client
         end
 
         logger.info("Request started:", stream.method, stream.path)
@@ -1340,7 +1344,7 @@ http.listen {
 
 -- Automatically pass current Trace ID when calling external services
 function call_external_service()
-    local trace_id = silly.tracepropagate()
+    local trace_id = trace.propagate()
     local response = http.get("http://other-service/api", {
         ["x-trace-id"] = tostring(trace_id),
     })
@@ -1654,6 +1658,7 @@ local silly = require "silly"
 local http = require "silly.net.http"
 local json = require "silly.encoding.json"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local prometheus = require "silly.metrics.prometheus"
 
 -- Configuration
@@ -1723,9 +1728,9 @@ local function logging_middleware(stream, next)
     -- Set or create trace ID
     local trace_id = tonumber(stream.header["x-trace-id"])
     if trace_id then
-        silly.traceset(trace_id)
+        trace.attach(trace_id)
     else
-        silly.tracespawn()
+        trace.spawn()
     end
 
     logger.info("Request:", stream.method, stream.path, "from", stream.remoteaddr)

docs/src/en/guides/logging-monitoring.md

@@ -27,7 +27,7 @@ The Silly framework provides built-in support for all three aspects:
 
 - `silly.logger`: Hierarchical logging system with log rotation support
 - `silly.metrics.prometheus`: Prometheus metrics collection and export
-- `silly.tracespawn/traceset`: Distributed trace ID generation and propagation
+- `trace.spawn/trace.attach`: Distributed trace ID generation and propagation
 
 ## Logging System
 
@@ -37,6 +37,7 @@ The Silly framework provides built-in support for all three aspects:
 
 ```lua
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 -- Set log level (only output INFO and above)
 logger.setlevel(logger.INFO)
@@ -89,6 +90,7 @@ Choose appropriate log levels based on different scenarios:
 
 ```lua
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 -- Production environment: use INFO level
 logger.setlevel(logger.INFO)
@@ -110,6 +112,7 @@ Use formatted log functions (`*f` series) to improve log readability:
 
 ```lua
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 -- Use string.format style
 logger.infof("User [%s] completed %d operations in %d seconds",
@@ -129,6 +132,7 @@ For easier log analysis, use structured log format:
 
 ```lua
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local json = require "silly.encoding.json"
 
 -- Define log helper function
@@ -194,6 +198,7 @@ In production environments, dynamically adjust log levels via signals to avoid s
 
 ```lua
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local signal = require "silly.signal"
 
 -- Initialize to INFO level
@@ -367,6 +372,7 @@ An HTTP service example with complete monitoring:
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local prometheus = require "silly.metrics.prometheus"
 
 -- Define metrics
@@ -500,6 +506,7 @@ Silly provides a distributed trace ID system where each coroutine has an indepen
 local silly = require "silly"
 local task = require "silly.task"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 task.fork(function()
     -- Create new trace ID (if current coroutine doesn't have one)
@@ -518,32 +525,38 @@ In microservice architecture, trace IDs need to be propagated to downstream serv
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local httpc = http.newclient()
 -- Service A: Initiate HTTP request
 local function call_service_b()
     -- Generate trace ID for propagation
     local trace_id = trace.propagate()
     logger.info("Calling service B")
 
-    -- Pass trace ID via HTTP Header
-    local response = httpc:request {
-        method = "POST",
-        url = "http://service-b:8080/api/process",
-        headers = {
+    -- Pass trace ID via HTTP header
+    local stream, err = httpc:request(
+        "POST",
+        "http://service-b:8080/api/process",
+        {
             ["X-Trace-Id"] = tostring(trace_id),
-        },
-        body = '{"data": "value"}',
-    }
+            ["content-type"] = "application/json",
+        }
+    )
+    if not stream then
+        return nil, err
+    end
 
-    return response
+    stream:closewrite('{"data": "value"}')
+    local body, status = stream:readall()
+    return {status = status, body = body}
 end
 
 -- Service B: Receive request and use incoming trace ID
 local server = http.listen {
     addr = "0.0.0.0:8080",
     handler = function(stream)
         -- Extract and set trace ID
-        local trace_id = tonumber(stream.headers["x-trace-id"])
+        local trace_id = tonumber(stream.header["x-trace-id"])
         if trace_id then
             trace.attach(trace_id)
         else
@@ -564,6 +577,7 @@ When making RPC calls using `silly.net.cluster`, trace IDs are automatically pro
 ```lua
 local cluster = require "silly.net.cluster"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 
 -- Create cluster service
 cluster.serve {
@@ -593,6 +607,7 @@ Integrate trace ID into logs to achieve complete request tracking:
 ```lua
 local silly = require "silly"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local json = require "silly.encoding.json"
 
 -- Structured log helper function
@@ -758,6 +773,7 @@ You can also implement simple alert logic within the application:
 local silly = require "silly"
 local time = require "silly.time"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local prometheus = require "silly.metrics.prometheus"
 
 -- Define alert thresholds
@@ -854,6 +870,7 @@ A production-grade HTTP service example with complete logging, monitoring, and t
 local silly = require "silly"
 local http = require "silly.net.http"
 local logger = require "silly.logger"
+local trace = require "silly.trace"
 local signal = require "silly.signal"
 local time = require "silly.time"
 local prometheus = require "silly.metrics.prometheus"
@@ -971,16 +988,16 @@ local function handle_request(stream)
     http_requests_in_flight:inc()
 
     -- Get or create trace ID
-    local trace_id = tonumber(stream.headers["x-trace-id"])
+    local trace_id = tonumber(stream.header["x-trace-id"])
     if trace_id then
-        silly.traceset(trace_id)
+        trace.attach(trace_id)
     else
-        silly.tracespawn()
-        trace_id = silly.tracepropagate()  -- Get current trace ID for response header
+        trace.spawn()
+        trace_id = trace.propagate()  -- Get current trace ID for response header
     end
 
     -- Record request size
-    local req_size = tonumber(stream.headers["content-length"]) or 0
+    local req_size = tonumber(stream.header["content-length"]) or 0
     http_request_size:observe(req_size)
 
     -- Route handling
@@ -1044,7 +1061,7 @@ local server = http.listen {
     handler = function(stream)
         local ok, err = silly.pcall(handle_request, stream)
         if not ok then
-            silly.tracespawn()  -- Create new trace ID
+            trace.spawn()  -- Create new trace ID
             logger.error("Request handling failed:", err)
 
             stream:respond(500, {["content-type"] = "application/json"})

docs/src/en/guides/tls-configuration.md

@@ -573,7 +573,7 @@ signal.register("SIGUSR1", function()
     end
 
     -- Hot reload certificates
-    local success, reload_err = tls.reload(listenfd, {
+    local success, reload_err = listenfd:reload({
         certs = {{cert = cert_pem, key = key_pem}}
     })
 
@@ -779,7 +779,7 @@ local function get_connection(host, port)
 
     -- Create new connection
     local ip = dns.lookup(host, dns.A)
-    conn = tls.connect(ip .. ":" .. port, nil, host, {"http/1.1"})
+    conn = tls.connect(ip .. ":" .. port, {hostname = host, alpnprotos = {"http/1.1"}})
 
     if conn then
         connection_pool[key] = conn

docs/src/en/reference/metrics/collector.md

@@ -783,10 +783,10 @@ local server = http.listen {
                 ["content-type"] = "text/plain; version=0.0.4; charset=utf-8",
                 ["content-length"] = #metrics_data,
             })
-            stream:close(metrics_data)
+            stream:closewrite(metrics_data)
         else
             stream:respond(404)
-            stream:close("Not Found")
+            stream:closewrite("Not Found")
         end
     end
 }

docs/src/en/reference/metrics/counter.md

@@ -533,10 +533,10 @@ local server = http.listen {
                 ["content-type"] = "text/plain; version=0.0.4; charset=utf-8",
                 ["content-length"] = #metrics_data,
             })
-            stream:close(metrics_data)
+            stream:closewrite(metrics_data)
         else
             stream:respond(404)
-            stream:close("Not Found")
+            stream:closewrite("Not Found")
         end
     end
 }

docs/src/en/reference/metrics/histogram.md

@@ -671,7 +671,7 @@ task.fork(function()
                 ["content-type"] = "application/json",
                 ["content-length"] = #response_body
             })
-            stream:close(response_body)
+            stream:closewrite(response_body)
 
             -- Record metrics
             local duration = (silly.time.now() - start_time) / 1000
@@ -690,10 +690,10 @@ task.fork(function()
                     ["content-type"] = "text/plain; version=0.0.4; charset=utf-8",
                     ["content-length"] = #metrics
                 })
-                stream:close(metrics)
+                stream:closewrite(metrics)
             else
                 stream:respond(404, {["content-type"] = "text/plain"})
-                stream:close("Not Found")
+                stream:closewrite("Not Found")
             end
         end
     }

docs/src/en/reference/metrics/prometheus.md

@@ -359,11 +359,11 @@ local server = http.listen {
         ["content-type"] = "text/plain; version=0.0.4; charset=utf-8",
         ["content-length"] = #metrics,
       })
-      stream:close(metrics)
+      stream:closewrite(metrics)
     else
       -- Business logic
       stream:respond(200, {["content-type"] = "text/plain"})
-      stream:close("Hello World")
+      stream:closewrite("Hello World")
 
       -- Record metrics
       local duration = os.clock() - start
@@ -428,19 +428,19 @@ local server = http.listen {
       stream:respond(200, {
         ["content-type"] = "text/plain; version=0.0.4; charset=utf-8",
       })
-      stream:close(metrics)
+      stream:closewrite(metrics)
       requests_in_flight:dec()
       return
     end
 
     -- Record request size
-    local req_size = stream.headers["content-length"] or 0
+    local req_size = stream.header["content-length"] or 0
     request_size:observe(tonumber(req_size))
 
     -- Business logic
     local response_data = "Response data"
     stream:respond(200, {["content-type"] = "text/plain"})
-    stream:close(response_data)
+    stream:closewrite(response_data)
 
     -- Record response metrics
     local duration = os.clock() - start
@@ -993,10 +993,10 @@ local metrics_server = http.listen {
       stream:respond(200, {
         ["content-type"] = "text/plain; version=0.0.4",
       })
-      stream:close(metrics)
+      stream:closewrite(metrics)
     else
       stream:respond(404)
-      stream:close("Not Found")
+      stream:closewrite("Not Found")
     end
   end
 }

docs/src/en/reference/net/cluster.md

@@ -1077,7 +1077,7 @@ end)
 Cluster automatically propagates trace IDs:
 
 ```lua
--- Client initiates request, automatically carries current trace ID using silly.tracepropagate()
+-- Client initiates request, automatically carries current trace ID using trace.propagate()
 local resp = cluster.call(peer, "ping", data)
 
 -- Server processes, trace ID is automatically set by cluster