# 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 ](/en/docs/net/web)

## Request data

| API | Description |
| ------ | ------ |
| [web.get](/en/docs/web/get) | Read URL query parameter object. |
| [web.post](/en/docs/web/post) | Read form POST field object. |
| [web.cookie](/en/docs/web/cookie) | Read the request Cookie object, and also write back the Cookie status after the request is completed. |
| [web.session](/en/docs/web/session) | Read and save the current request Session object. |
| [web.files](/en/docs/web/files) | Read the uploaded file object. |
| [web.server](/en/docs/web/server) | Read request and server information. |
| [web.url](/en/docs/web/url) | Read the current request path. |
| [web.method](/en/docs/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](/en/docs/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](/en/docs/web/header) | Set one or a group of response headers. |
| [web.status_code](/en/docs/web/status_code) | Set HTTP response status code. |
| [web.redirect](/en/docs/web/redirect) | Set HTTP redirect address. |
| [web.send_file](/en/docs/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 ](/en/docs/web/io-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](/en/docs/web/io-policy) 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

```bt
name = web.get.name
web.header('Content-Type', 'text/plain; charset=utf-8')

// Output: BT
echo(name)
```

## 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 ](/en/docs/net/web).
- `web.send_file()` reuses the same set of file response capabilities, supporting ETag, Last-Modified, conditional requests and Range.