Interface
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
}
Description: The CookieJar is used by the Client to manage the Cookie.
It has two static functions:
- toCookieString: converts ArrayList<Cookie> to a string to set the Cookie header of a request.
- parseSetCookieHeader: parses the
Set-Cookieheader in the received response.
If CookieJar is configured for Client, Cookie is automatically received, sent, and parsed.
Note:
prop isHttp
prop isHttp: Bool
Description: Specifies whether the CookieJar is used for the HTTP protocol.
- If isHttp is set to true, only the Cookie instances from the HTTP protocol are stored.
- If isHttp is set to false, only the Cookie instances from non-HTTP protocols are stored, and the Cookie instances for which httpOnly is set are not stored.
Type: Bool
prop rejectPublicSuffixes
prop rejectPublicSuffixes: ArrayList<String>
Description: Obtains the public suffixes configuration. The configuration is a domain blacklist and rejects the Cookie whose domain value is public suffixes.
Note:
If the Cookie is from the same host as the domain, the blacklist does not take effect.
static func createDefaultCookieJar(ArrayList<String>, Bool)
static func createDefaultCookieJar(rejectPublicSuffixes: ArrayList<String>, isHttp: Bool): CookieJar
Description: Constructs the default CookieJar instance for managing Cookie.
For details about the management requirements of the default CookieJar, see RFC 6265 5.3..
Parameters:
- rejectPublicSuffixes: ArrayList<String>: public suffixes configured by the user. For Cookie management, cookies whose domain value is public suffixes (except the Cookie from the same host as the domain) are rejected for security purposes. For details about public suffixes, see PUBLIC SUFFIX LIST.
- isHttp: Bool: whether the CookieJar is used for the HTTP protocol. If isHttp is set to true, only the Cookie instances from the HTTP protocol are stored.
Returns:
static func parseSetCookieHeader(HttpResponse)
static func parseSetCookieHeader(response: HttpResponse): ArrayList<Cookie>
Description: Parses the Set-Cookie header in the response.
This function is used to parse the Set-Cookie header in a response and return the parsed ArrayList<Cookie>. For details about the rules for parsing the Set-Cookie header, see RFC 6265 5.2..
Parameters:
- response: HttpResponse: response to be parsed
Returns:
static func toCookieString(ArrayList<Cookie>)
static func toCookieString(cookies: ArrayList<Cookie>): String
Description: Converts ArrayList<Cookie> to a string for the Cookie header.
This function is used to convert the input ArrayList<Cookie> array to the Cookie header string format specified by the protocol. For details, see RFC 6265 5.4.4..
Parameters:
Returns:
func clear()
func clear(): Unit
Description: Clears all Cookie instances.
By default, the CookieJarImpl clears all Cookie instances in the CookieJar.
func getCookies(URL)
func getCookies(url: URL): ArrayList<Cookie>
Description: Obtains ArrayList<Cookie> from the CookieJar.
For details about the requirements of the function that obtains ArrayList<Cookie> for cookieJarImpl by default, see RFC 6265 5.4.. The obtained ArrayList<Cookie> can be converted to the value string of the Cookie header by calling toCookieString.
Parameters:
Returns:
func removeCookies(String)
func removeCookies(domain: String): Unit
Description: Removes the Cookie of a domain from the CookieJar.
Note:
By default, the CookieJarImpl removes only the Cookie of the specific domain, while the Cookie of the subdomains of the domain is not removed.
Parameters:
Throws:
- IllegalArgumentException: If the input domain is an empty string or invalid, this exception is thrown. For details about the rules for valid domains, see the Cookie parameter document.
func storeCookies(URL, ArrayList<Cookie>)
func storeCookies(url: URL, cookies: ArrayList<Cookie>): Unit
Description: Saves ArrayList<Cookie> to CookieJar.
If the number of Cookie instances stored in the CookieJar exceeds the upper limit (3000), at least 1,000 Cookie instances must be cleared from the CookieJar before other instances can be saved. For details about the priority for clearing the Cookie instances in the CookieJar, see RFC 6265 5.3.12..
Cookie instances are cleared in the following sequence:
- Expired Cookie instances
- Cookie instances other than the first 50 ones
- Cookie instances with the same priority but having an earlier
last-accesstime
Parameters:
interface HttpRequestDistributor
public interface HttpRequestDistributor
Description: Specifies an HTTP request distributor interface which distributes a request to the corresponding HttpRequestHandler based on the path in the URL.
Note:
This implementation provides a default HttpRequestDistributor, which is not thread-safe. By default,
ProtocolServiceinstances of HTTP/1.1 and HTTP/2 in the Cangjie standard library are provided. In addition, the register operation can be performed only before the server is started. A register operation after the server is started leads to an undefined result. If the user wants to perform a register operation after the server is started, a thread-safe HttpRequestDistributor is required for implementation.
func distribute(String)
func distribute(path: String): HttpRequestHandler
Description: Distributes request handlers. If the corresponding request handler is not found, NotFoundHandler and status code 404 are returned.
Parameters:
- path: String: request path
Returns:
- HttpRequestHandler: The request handler is returned.
func register(String, (HttpContext) -> Unit)
func register(path: String, handler: (HttpContext) -> Unit): Unit
Description: Registers request handlers.
Parameters:
- path: String: request path
- handler: (HttpContext) ->Unit: request processing function
Throws:
- HttpException: If a request handler has been registered in the request path, this exception is thrown.
func register(String, HttpRequestHandler)
func register(path: String, handler: HttpRequestHandler): Unit
Description: Registers request handlers.
Parameters:
- path: String: request path
- handler: HttpRequestHandler: request handler
Throws:
- HttpException: If a request handler has been registered in the request path, this exception is thrown.
interface HttpRequestHandler
public interface HttpRequestHandler {
func handle(ctx: HttpContext): Unit
}
Description: Specifies the HTTP request handler.
The HTTP server processes the HTTP request from the client through the handler. In the handler, the user can obtain the detailed information about the HTTP request, including the header and body, construct the HTTP response, including the header and body, and send the response to the client directly (alternatively, the response can be sent by the server).
When building an HTTP server, the user needs to register one or more handlers through the HttpRequestDistributor of the server. When an HTTP request from the client is received, the distributor distributes the request to the corresponding handler based on the path of the URL in the request.
Note:
To prevent the DNS rebinding attack, the application verifies the value of the Host request header of the request in the handler logic to check whether the value is an authoritative host name recognized by the application.
func handle(HttpContext)
func handle(ctx: HttpContext): Unit
Description: Processes HTTP requests.
Parameters:
- ctx: HttpContext: HTTP request context
interface ProtocolServiceFactory
public interface ProtocolServiceFactory {
func create(protocol: Protocol, socket: StreamingSocket): ProtocolService
}
Description: Sets the HTTP service instance factory which is used to generate ProtocolService instances.
The default implementation is provided for ServerBuilder. By default, ProtocolService instances of HTTP/1.1 and HTTP/2 in the Cangjie standard library are provided.
func create()
func create(protocol: Protocol, socket: StreamingSocket): ProtocolService
Description: Creates a protocol service instance based on the protocol.
Parameters:
- protocol: Protocol: protocol version, such as HTTP1_0, HTTP1_1, and HTTP2_0
- socket: StreamingSocket: socket from the client
Returns:
- ProtocolService: protocol service instance