目录

接口

interface CookieJar

public interface CookieJar {
    prop isHttp: Bool
    prop rejectPublicSuffixes: ArrayList<String>
    static func createDefaultCookieJar(rejectPublicSuffixes: ArrayList<String>, isHttp: Bool): CookieJar
    static func parseSetCookieHeader(response: HttpResponse): ArrayList<Cookie>
    static func toCookieString(cookies: ArrayList<Cookie>): String
    func clear(): Unit
    func getCookies(url: URL): ArrayList<Cookie>
    func removeCookies(domain: String): Unit
    func storeCookies(url: URL, cookies: ArrayList<Cookie>): Unit
}

功能：CookieJar 是 Client 用来管理 Cookie 的工具。

其有两个静态函数：

如果 Client 配置了 CookieJar，那么 Cookie 的解析收发都是自动的。

[h2]prop isHttp

prop isHttp: Bool

功能：该 CookieJar 是否用于 HTTP 协议。

类型：Bool

[h2]prop rejectPublicSuffixes

prop rejectPublicSuffixes: ArrayList<String>

功能：获取 public suffixes 配置，该配置是一个 domain 黑名单，会拒绝 domain 值为 public suffixes 的 Cookie。

如果该 Cookie 来自于与 domain 相同的 host，黑名单就不会生效。

类型：ArrayList<String>

[h2]static func createDefaultCookieJar(ArrayList<String>, Bool)

static func createDefaultCookieJar(rejectPublicSuffixes: ArrayList<String>, isHttp: Bool): CookieJar

功能：构建默认的管理 Cookie 的 CookieJar 实例。

默认的 CookieJar 的管理要求参考 RFC 6265 5.3.。

参数：

返回值：

[h2]static func parseSetCookieHeader(HttpResponse)

static func parseSetCookieHeader(response: HttpResponse): ArrayList<Cookie>

功能：解析 response 中的 Set-Cookie header。

该函数解析 response 中的 Set-Cookie header，并返回解析出的 ArrayList<Cookie>，解析 Set-Cookie header 的具体规则见 RFC 6265 5.2.。

参数：

返回值：

[h2]static func toCookieString(ArrayList<Cookie>)

static func toCookieString(cookies: ArrayList<Cookie>): String

功能：将 ArrayList<Cookie> 转成字符串，用于 Cookie header。

该函数会将传入的 ArrayList<Cookie> 数组转成协议规定的 Cookie header 的字符串形式，见 RFC 6265 5.4.4.。

参数：

返回值：

[h2]func clear()

func clear(): Unit

功能：清除全部 Cookie。

默认实现 CookieJarImpl 会清除 CookieJar 中的所有 Cookie。

[h2]func getCookies(URL)

func getCookies(url: URL): ArrayList<Cookie>

功能：从 CookieJar 中取出 ArrayList<Cookie>。

默认实现 cookieJarImpl 的取 ArrayList<Cookie> 函数的具体要求见 RFC 6265 5.4.，对取出的 ArrayList<Cookie> 调用 toCookieString 可以将取出的 ArrayList<Cookie> 转成 Cookie header 的 value 字符串。

参数：

返回值：

[h2]func removeCookies(String)

func removeCookies(domain: String): Unit

功能：从 CookieJar 中移除某个 domain 的 Cookie。

默认实现 CookieJarImpl 的移除某个 domain 的 Cookie 只会移除特定 domain 的 Cookie，domain 的 subdomain 的 Cookie 并不会移除。

参数：

异常：

[h2]func storeCookies(URL, ArrayList<Cookie>)

func storeCookies(url: URL, cookies: ArrayList<Cookie>): Unit

功能：将 ArrayList<Cookie> 存进 CookieJar。

如果往 CookieJar 中存 Cookie 时超过了上限（3000 条），那么至少清除 CookieJar 中 1000 条 Cookie 再往里存储。清除 CookieJar 中 Cookie 的优先级见 RFC 6265 5.3.12.。

Cookie按如下顺序清除：

参数：

interface HttpRequestDistributor

public interface HttpRequestDistributor

功能：Http request 分发器接口，将一个 request 按照 url 中的 path 分发给对应的 HttpRequestHandler 处理。

本实现提供一个默认的 HttpRequestDistributor，该 distributor 非线程安全。

默认实现提供仓颉标准库中 HTTP/1.1、HTTP/2 的 ProtocolService 实例。

且只能在启动 server 前 register，启动后再次 register，结果未定义。

如果用户希望在启动 server 后还能够 register，需要自己提供一个线程安全的 HttpRequestDistributor 实现。

[h2]func distribute(String)

func distribute(path: String): HttpRequestHandler

功能：分发请求处理器，未找到对应请求处理器时，将返回 NotFoundHandler 以返回 404 状态码。

参数：

返回值：

[h2]func register(String, (HttpContext) -> Unit)

func register(path: String, handler: (HttpContext) -> Unit): Unit

功能：注册请求处理器。

参数：

异常：

[h2]func register(String, HttpRequestHandler)

func register(path: String, handler: HttpRequestHandler): Unit

功能：注册请求处理器。

参数：

异常：

interface HttpRequestHandler

public interface HttpRequestHandler {
    func handle(ctx: HttpContext): Unit
}

功能：Http request 处理器。

http server 端通过 handler 处理来自客户端的 http request；在 handler 中用户可以获取 http request 的详细信息，包括 header、body；在 handler 中，用户可以构造 http response，包括 header、body，并且可以直接发送 response 给客户端，也可交由 server 发送。

用户在构建 http server 时，需手动通过 server 的 HttpRequestDistributor 注册一个或多个 handler，当一个客户端 http request 被接收，distributor 按照 request 中 url 的 path 分发给对应的 handler 处理。

[h2]func handle(HttpContext)

func handle(ctx: HttpContext): Unit

功能：处理 Http 请求。

参数：

interface ProtocolServiceFactory

public interface ProtocolServiceFactory {
    func create(protocol: Protocol, socket: StreamingSocket): ProtocolService
}

功能：Http 服务实例工厂，用于生成 ProtocolService 实例。

ServerBuilder 提供默认的实现。默认实现提供仓颉标准库中 HTTP/1.1、HTTP/2 的 ProtocolService 实例。

[h2]func create()

func create(protocol: Protocol, socket: StreamingSocket): ProtocolService

功能：根据协议创建协议服务实例。

参数：

返回值：