web request context

Function

The web service runtime injects web objects into the script. The web object consists of request data fields and response control functions. The specific structure is shown in the table below and the corresponding API page.

How to enable Web service please read: Web service

Request data

API	Description
web.get	Read URL query parameter object.
web.post	Read form POST field object.
web.cookie	Read the request Cookie object, and also write back the Cookie status after the request is completed.
web.session	Read and save the current request Session object.
web.files	Read the uploaded file object.
web.server	Read request and server information.
web.url	Read the current request path.
web.method	Read the current HTTP request method.

Request object overview

API	Type	Structure
web.get	Object	Query parameter name -> String.
web.post	Object	Form field name -> String/Array.
web.cookie	Object	Cookie name -> String and write back the response cookie at the end of the request.
web.session	Object	Session key name -> JSON serializable value.
web.files	Object	Upload field name -> file information object array; see web.files] for the file information field.
web.server	Object	method、version、scheme、headers、local_addr、remote_addr、ip、port。

Response Control

API	Description
web.header	Set one or a group of response headers.
web.status_code	Set HTTP response status code.
web.redirect	Set HTTP redirect address.
web.send_file	Send local files directly, suitable for large response downloads.

Blocking API strategy

Web request scripts will enter the BT process-level blocking pool for execution as a whole to avoid blocking Tokio Web workers. For the allow and deny rules for sleep, fs, process, reqwest, mysql, task, device in Web requests, see: Web blocking API policy .

Resource Boundaries

Dynamic Web requests check request bodies, headers, uploaded files and dynamic response sizes. Oversized requests or uploads return HTTP 413 with an English error. Oversized dynamic responses fail before response writeback. Static files and web.send_file() payloads stream separately and are exempt from BT_WEB_RESPONSE_BODY_LIMIT.

On main for the next release, collected script output is also checked before each append, including print, println, exit and template child output. Exceeding the UTF-8 byte limit stops subsequent script statements. Final returned values remain checked before sending; this is an output-buffer limit, not a total VM allocation limit. Collected script output remains bounded even if web.send_file() has been selected. See request deadlines for cancellation boundaries.

Environment variable	Default value	Description
BT_WEB_REQUEST_BODY_LIMIT	16777216	The upper limit of the request body, in bytes, including form and multipart uploads.
BT_WEB_RESPONSE_BODY_LIMIT	67108864	The upper limit of BT script dynamic response body, in bytes.
BT_WEB_HEADER_COUNT_LIMIT	128	Maximum number of headers requested.
BT_WEB_HEADER_BYTES_LIMIT	65536	Request the upper limit of cumulative bytes of header name and value.
BT_WEB_UPLOAD_FILE_LIMIT	33554432	The upper limit of the size of a single uploaded file, in bytes.

Examples

Notes

The web object only exists during the execution of the web request.

- Response control status is written to the HTTP response uniformly after the script execution ends.

Uploaded files will first pass the total request limit, and then pass the single file limit; for large file downloads, static files or web.send_file() files should be used first.

- Static files support ETag, Last-Modified, Conditional Request and Range; static cache policy is configured in net.listen static.cache_control of Web Service .

web.send_file() reuses the same set of file response capabilities, supporting ETag, Last-Modified, conditional requests and Range.