第 3 章：HTTP 服务基础

本章以 /ping 为例，说明服务对象、路由、Handler、请求对象和返回值约定。

1. 完整程序

#include <sttnet.h>
#include <iostream>

int main()
{
    using namespace stt::network;
    using stt::system::ServerSetting;

    // 退出信号在线程创建前完成屏蔽。
    if(!ServerSetting::blockTerminationSignals())
        return 1;

    HttpServer server;

    server.setFunction("/ping",
        [](HttpServerFDHandler &client, HttpRequestInformation &) {
            // 1：本阶段成功；-2：发送失败并关闭连接。
            return client.sendText("pong") ? 1 : -2;
        });

    if(!server.startListen(8080))
        return 2;

    std::cout << "http://127.0.0.1:8080/ping\n";
    ServerSetting::waitForTerminationSignal();
    return server.close() ? 0 : 3;
}

2. 程序结构说明

blockTerminationSignals() 在线程创建前执行，为后续同步信号等待与安全退出建立信号模型。
HttpServer 构造完成后具有默认安全模块，以及连接、接收和队列上限。
setFunction("/ping", ...) 将 /ping 注册为 path 路由；默认路由 key 为 request.loc。
Handler 负责当前连接的发送操作，请求对象保存 method、path、header 和 body。
startListen(8080) 启动监听与 Reactor；false 表示监听未启动。
主线程收到 SIGINT/SIGTERM 后，在正常线程上下文中调用 server.close()。

3. 回调返回值概览

值	准确含义
`1`	当前阶段成功；同一路由存在后续阶段时，下一阶段继续执行。
`0`	当前阶段已交给 WorkerPool；Worker 完成后从下一阶段继续。
`-1`	本次请求或消息的后续阶段停止，连接保持打开。
`-2`	处理停止，连接关闭。

这些值是 STTNet 的流程控制，不是 HTTP 状态码。HTTP 404 要通过 sendText(..., "404 Not Found") 或 sendJson() 发送，return 404 不会发送 HTTP 状态码。

4. 路由找不到时

server.setGlobalSolveFunction(
    [](HttpServerFDHandler &client, HttpRequestInformation &) {
        return client.sendText("not found", "404 Not Found") ? 1 : -2;
    });