# net.listen Web Service

## Function

`net.listen({type: 'web'})` starts the BT Web service. Each request executes the site entry BT file and injects the `web` request context.

## Syntax

```bt
server = net.listen({
    type: 'web',
    bind: '127.0.0.1:8080',
    sites: [
        {
            root: 'web/',
            entry: 'main.bt',
            domains: ['localhost'],
            upload: {temp: 'temp/'},
            static: {
                route: '/static/{**}',
                path: 'web/static/',
                default: 'index.html',
                list: false,
                cache_control: 'public, max-age=3600',
                chunk_size: 1048576
            },
            ssl: {cert: 'ssl/cert.pem', key: 'ssl/key.pem'}
        }
    ]
})
```

## Parameters

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to web. |
| bind | String | No | 0.0.0.0:8080 | Listening address. |
| sites | Array | Yes | None | Array of site configurations, at least one. |
| sites[].root | String | No | web/ | Site root directory. |
| sites[].entry | String | No | main.bt | Request entry BT file. |
| sites[].domains | Array | No | [] | Host filter domain name. |
| sites[].upload.temp | String | No | temp/ | Temporary directory for uploading files. |
| sites[].static | Object | No | None | Static-file configuration object; see the `static` fields below. |
| sites[].ssl | Object | No | None | TLS certificate configuration object; see the `ssl` fields below. |

## The sites field

`sites` is the site configuration array. Each site object field is as follows:

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| root | String | No | `web/` | Site root directory. Relative paths such as entry scripts and default static directories will be resolved based on this directory. |
| entry | String | No | `main.bt` | BT entry file executed for each dynamic request. |
| domains | Array | No | `[]` | Host filter domain name list. When it is an empty array, it is used as the default site without domain name restrictions. |
| upload | Object | No | None | Upload configuration object; see the `upload` fields below. |
| static | Object | No | None | Static file configuration object. Passing in this object enables static file serving. |
| ssl | Object | No | None | TLS certificate configuration object. Both `cert` and `key` must be provided to enable HTTPS. |

## upload field

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| temp | String | No | `temp/` | Temporary storage directory for uploaded files. `web.files[*].path` and `web.files[*].file` will point to the saved file here. |

## static field

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| route | String | No | `/static/{**}` | Static resource route matching rules. |
| path | String | No | `root/static` | Static file directory. If not filled in, use the `static` directory under the root of the current site. |
| default | String | No | `index.html` | The default file name that is attempted to be returned when accessing the directory. |
| list | Bool | No | `false` | Whether to allow directory list display. Production environments usually keep false. |
| cache_control | String | No | Empty string | The static file responded successfully to the `Cache-Control` header written. When empty, the header is not actively written. |
| chunk_size | Int | No | `0` | The number of bytes read in chunks of static files. Less than or equal to 0 uses the framework default value of 1048576. |

## ssl field

| Field | Type | Required | Default | Description |
|------|------|------|------|------|
| cert | String | Yes | None | Path to the TLS certificate file. |
| key | String | Yes | None | TLS private key file path. |

## Return Value

| Type | Description |
|------|------|
| WebServer | Returns the Web service handle. |

## WebServer fields and methods

| Name | Type | Description |
|------|------|------|
| addr | String | Actual listening address, usually in the format `host:port`. |
| type | String | Fixed to `web`. |
| close() | Fn -> Bool | Close the background web service and return true successfully. |

## Examples

```bt
// Start a minimal web service, and execute web/main.bt after the request comes in.
server = net.listen({
    type: 'web',
    bind: '127.0.0.1:8080',
    sites: [{root: 'web/', entry: 'main.bt'}]
})

// Output: web
echo(server.type)
```

## Notes

- The relative paths of root, upload.temp, static.path, ssl.cert, ssl.key are resolved based on the directory where the source code file is called; @ represents the project root.
 - TLS will not be enabled when either `ssl.cert` and `ssl.key` are empty.
- There are default upper limits for dynamic request bodies, headers, uploaded files and dynamic response bodies; for configuration methods, see [resource boundary description of web request context ](/en/docs/web).
 - Static files support `ETag`, `Last-Modified`, conditional requests and HTTP Range by default; `cache_control` is only responsible for additional write caching strategies.
- `chunk_size` controls the block read size of static files and does not read large files into memory at once.