# Web blocking API strategy

## Function

Describes the rules for operating slow I/O, blocking waits, and long-term background capabilities in the context of web requests.

The web request script will enter the BT process-level blocking pool for execution as a whole to avoid `fs`, short `sleep()`, template compilation, synchronization script logic, etc. from blocking Tokio Web workers. The number of threads, queue length, and default wait time of the blocking pool are controlled by the `BT_IO_*` configuration.

## Syntax

```bt
// View the current I/O runtime-boundary configuration
stats = BT.stats().io
```

## Parameters

No parameters.

## Return value

This page is a rule description and does not provide independent function return values.

## Web request rules

| API | Behavior in Web Requests | Boundaries |
| ------ | ------ | ------ |
| `sleep(ms)` | Allow short sleep. | `ms` cannot exceed `BT_IO_TIMEOUT_MS`, the default is 30000 milliseconds. |
| `pause()` | Rejected. | There is no interactive terminal for web requests. |
| `fs.*` | Allowed. | The entire request script runs in the blocking pool, subject to `BT_IO_BLOCKING_WORKERS`, `BT_IO_BLOCKING_QUEUE`, `BT_IO_TIMEOUT_MS`. |
| `process.status()` / `process.output()` / `process.child()` / `process.wait()` | Rejected. | These operations may wait synchronously on external processes or fork long-term child processes. |
| `reqwest.send()` | Allowed. | Using the shared I/O runtime, the default time for a single request is 30000 milliseconds; it can be set by `timeout(ms)`, but the overall web request is still subject to `BT_IO_TIMEOUT_MS`. |
| `mysql.all()` / `mysql.one()` / `mysql.exec()` | Allowed. | Using the shared I/O runtime and MySQL query timeouts, web requests overall are still subject to `BT_IO_TIMEOUT_MS`. |
| `task(fn, ...args)` | Allow background task submission. | `Task.on_done()`, `Task.await()`, `task_all()`, `task_race()` rejected in web request. |
| `device.*` | Allowed. | Serial port opening, reading and writing must rely on the timeout in the device configuration, and the entire web request is subject to `BT_IO_TIMEOUT_MS`. |

## Code Example

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

sleep(5)

// Output: ok
print 'ok'
```

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

task(fn() {
    return 1
}).await()

// Output: execution never reaches here
print 'done'
```

## Request deadline configuration

The cooperative cancellation rules in this section are available on `main` for the next release. Published 1.1.4 only stops waiting when the request timeout expires.

| Variable | Type | Required | Default | Range | Meaning |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `BT_IO_TIMEOUT_MS` | Integer environment variable | No | `30000` | Positive milliseconds | One deadline covering the blocking queue and script execution, shared by nested functions, includes, templates, `sleep`, and shared asynchronous I/O. |
| `BT_IO_BLOCKING_WORKERS` | Integer environment variable | No | Logical CPU count | `1..64` when configured | Maximum number of blocking workers shared by requests. |
| `BT_IO_BLOCKING_QUEUE` | Integer environment variable | No | `256` | `1..8192` | Maximum queued jobs; a full queue rejects new work. |

## Notes

- Expired queued scripts are skipped before user code runs. Running BT bytecode checks the deadline at bounded instruction intervals and before function calls. The deadline is cooperative, not a hard real-time guarantee.
- `sleep(ms)` still rejects durations above `BT_IO_TIMEOUT_MS`; otherwise it stops at the remaining request deadline. HTTP/MySQL waits use the smaller of their operation timeout and the remaining request time. Dropping the request waiter also signals cancellation.
- A timeout returns an HTTP error. BT cannot safely force-stop a native filesystem/device/FFI call or an extension host call already in progress; the worker is released after that call returns and cancellation is observed. Configure those operations' own timeouts or isolate long-running native work in a separate process.
- Cancellation does not undo file writes, database changes, sent network requests or other effects already performed. Explicitly submitted `task(...)` background jobs retain their independent lifecycle.
- A full queue returns an English error beginning with `The I/O blocking task queue is full`.
- CLI and desktop execution without a Web request budget retain their existing behavior.
- Run `examples/web-blocking-policy/main.bt` for API policy examples. Contributors can run `python tools/quality/verify-web-deadlines.py --bt target/debug/bt.exe` from the runtime repository on Windows; use `target/debug/bt` on Unix.