# 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'
```

## Notes

- `BT_IO_TIMEOUT_MS` Defaults to 30000 milliseconds and serves as the default upper limit for web request scripts to wait for results in the blocking pool.
- If the blocking pool queue is full, the request will return an explicit Chinese error: `I/O 阻塞任务队列已满`.
- Timeout will cause the current HTTP request to return an error, but the underlying operations that have entered the system blocking call cannot be safely forcibly interrupted by Rust; therefore, long-term external processes and non-timeout device operations should still be avoided in the Web.
- When you need a verification example, run `examples/web-blocking-policy/main.bt`.