Skip to content

Commit 3b3e04c

Browse files
bbopenbbopen
authored
Merge pull request #292 from bbopen/docs/0.9-263-http-docstring
docs(bridge): correct python_bridge docstring — no HTTP transport ships
2 parents fa94784 + d7ea4c2 commit 3b3e04c

5 files changed

Lines changed: 77 additions & 58 deletions

File tree

‎SECURITY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ Two environment-variable controls bound that surface:
1515
- Underscore-prefixed attributes are blocked by default. Set
1616
`TYWRAP_ALLOW_PRIVATE_ATTRS=1` only to opt out for trusted code.
1717

18-
No HTTP server ships with tywrap. `HttpBridge` is a client for a server that you
19-
run and secure.
18+
No HTTP server or server-side HTTP transport ships with tywrap. `HttpBridge`
19+
only connects to a server that you run and secure.
2020

2121
## Network exposure
2222

‎docs/guide/runtimes/http.md‎

Lines changed: 26 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# HTTP Bridge Guide
22

3-
`HttpBridge` connects to a Python server over HTTP. Use it when Python must run separately — including Deno Deploy, serverless environments, or distributed architectures.
3+
`HttpBridge` connects to a Python server over HTTP. Use it when Python must run
4+
separately — including Deno Deploy, serverless environments, or distributed
5+
architectures.
46

57
## When to Use HttpBridge
68

@@ -21,29 +23,34 @@ pip install tywrap-ir
2123
import { HttpBridge } from 'tywrap/http';
2224
import { setRuntimeBridge } from 'tywrap/runtime';
2325

24-
setRuntimeBridge(new HttpBridge({
25-
baseURL: 'http://localhost:8080',
26-
timeoutMs: 30000,
27-
headers: {
28-
'Authorization': 'Bearer your-token',
29-
},
30-
}));
26+
setRuntimeBridge(
27+
new HttpBridge({
28+
baseURL: 'http://localhost:8080',
29+
timeoutMs: 30000,
30+
headers: {
31+
Authorization: 'Bearer your-token',
32+
},
33+
})
34+
);
3135
```
3236

3337
## Options
3438

35-
| Option | Required | Default | Description |
36-
|--------|----------|---------|-------------|
37-
| `baseURL` | Yes | — | Base URL of the Python bridge server |
38-
| `headers` | No | `{}` | Additional HTTP headers (auth, CORS, etc.) |
39-
| `timeoutMs` | No | `30000` | Request timeout in milliseconds |
40-
| `codec` | No | Arrow | Codec options |
39+
| Option | Required | Default | Description |
40+
| ----------- | -------- | ------- | ------------------------------------------ |
41+
| `baseURL` | Yes | — | Base URL of the Python bridge server |
42+
| `headers` | No | `{}` | Additional HTTP headers (auth, CORS, etc.) |
43+
| `timeoutMs` | No | `30000` | Request timeout in milliseconds |
44+
| `codec` | No | Arrow | Codec options |
4145

4246
## Running the Python Server
4347

44-
`HttpBridge` expects a server that accepts POST requests with JSON/Arrow payloads. You must implement or deploy a compatible server endpoint. The protocol is stateless — each call is an independent POST request.
48+
`HttpBridge` expects a server that accepts POST requests with JSON/Arrow
49+
payloads. You must implement or deploy a compatible server endpoint. The
50+
protocol is stateless — each call is an independent POST request.
4551

46-
> **Note:** A built-in server command is not yet available. See the [API reference](/reference/api/) for the expected request/response format.
52+
> **Note:** tywrap does not ship an HTTP server. See the
53+
> [API reference](/reference/api/) for the expected request/response format.
4754
4855
## Apache Arrow
4956

@@ -58,10 +65,10 @@ registerArrowDecoder(bytes => tableFromIPC(bytes));
5865

5966
## Environment Variables
6067

61-
| Var | Purpose |
62-
|-----|---------|
68+
| Var | Purpose |
69+
| ---------------------------- | ---------------------------- |
6370
| `TYWRAP_CODEC_FALLBACK=json` | Disable Arrow, use JSON only |
64-
| `TYWRAP_CODEC_MAX_BYTES` | Cap max response size |
71+
| `TYWRAP_CODEC_MAX_BYTES` | Cap max response size |
6572

6673
See the [environment variables reference](/reference/env-vars).
6774

‎docs/public/llms-full.txt‎

Lines changed: 34 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2031,7 +2031,9 @@ Run `tywrap generate` during your build and load Pyodide at runtime (CDN or self
20312031
<!-- Source: docs/guide/runtimes/http.md -->
20322032
# HTTP Bridge Guide
20332033

2034-
`HttpBridge` connects to a Python server over HTTP. Use it when Python must run separately — including Deno Deploy, serverless environments, or distributed architectures.
2034+
`HttpBridge` connects to a Python server over HTTP. Use it when Python must run
2035+
separately — including Deno Deploy, serverless environments, or distributed
2036+
architectures.
20352037

20362038
## When to Use HttpBridge
20372039

@@ -2052,29 +2054,34 @@ pip install tywrap-ir
20522054
import { HttpBridge } from 'tywrap/http';
20532055
import { setRuntimeBridge } from 'tywrap/runtime';
20542056

2055-
setRuntimeBridge(new HttpBridge({
2056-
baseURL: 'http://localhost:8080',
2057-
timeoutMs: 30000,
2058-
headers: {
2059-
'Authorization': 'Bearer your-token',
2060-
},
2061-
}));
2057+
setRuntimeBridge(
2058+
new HttpBridge({
2059+
baseURL: 'http://localhost:8080',
2060+
timeoutMs: 30000,
2061+
headers: {
2062+
Authorization: 'Bearer your-token',
2063+
},
2064+
})
2065+
);
20622066
```
20632067

20642068
## Options
20652069

2066-
| Option | Required | Default | Description |
2067-
|--------|----------|---------|-------------|
2068-
| `baseURL` | Yes | — | Base URL of the Python bridge server |
2069-
| `headers` | No | `{}` | Additional HTTP headers (auth, CORS, etc.) |
2070-
| `timeoutMs` | No | `30000` | Request timeout in milliseconds |
2071-
| `codec` | No | Arrow | Codec options |
2070+
| Option | Required | Default | Description |
2071+
| ----------- | -------- | ------- | ------------------------------------------ |
2072+
| `baseURL` | Yes | — | Base URL of the Python bridge server |
2073+
| `headers` | No | `{}` | Additional HTTP headers (auth, CORS, etc.) |
2074+
| `timeoutMs` | No | `30000` | Request timeout in milliseconds |
2075+
| `codec` | No | Arrow | Codec options |
20722076

20732077
## Running the Python Server
20742078

2075-
`HttpBridge` expects a server that accepts POST requests with JSON/Arrow payloads. You must implement or deploy a compatible server endpoint. The protocol is stateless — each call is an independent POST request.
2079+
`HttpBridge` expects a server that accepts POST requests with JSON/Arrow
2080+
payloads. You must implement or deploy a compatible server endpoint. The
2081+
protocol is stateless — each call is an independent POST request.
20762082

2077-
> **Note:** A built-in server command is not yet available. See the [API reference](https://bbopen.github.io/tywrap/reference/api/) for the expected request/response format.
2083+
> **Note:** tywrap does not ship an HTTP server. See the
2084+
> [API reference](https://bbopen.github.io/tywrap/reference/api/) for the expected request/response format.
20782085

20792086
## Apache Arrow
20802087

@@ -2089,10 +2096,10 @@ registerArrowDecoder(bytes => tableFromIPC(bytes));
20892096

20902097
## Environment Variables
20912098

2092-
| Var | Purpose |
2093-
|-----|---------|
2099+
| Var | Purpose |
2100+
| ---------------------------- | ---------------------------- |
20942101
| `TYWRAP_CODEC_FALLBACK=json` | Disable Arrow, use JSON only |
2095-
| `TYWRAP_CODEC_MAX_BYTES` | Cap max response size |
2102+
| `TYWRAP_CODEC_MAX_BYTES` | Cap max response size |
20962103

20972104
See the [environment variables reference](https://bbopen.github.io/tywrap/reference/env-vars).
20982105

@@ -2378,14 +2385,14 @@ today.
23782385

23792386
These affect the Python bridge or decoded runtime behavior.
23802387

2381-
| Variable | Scope | Default | Purpose |
2382-
| ---------------------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
2383-
| `TYWRAP_CODEC_FALLBACK` | Python bridge | unset | Set to `json` to allow JSON fallback when Arrow encoding is unavailable |
2384-
| `TYWRAP_CODEC_MAX_BYTES` | Python bridge | unset | Reject response payloads larger than this byte count (applied post-reassembly) |
2385-
| `TYWRAP_REQUEST_MAX_BYTES` | Python bridge | unset | Reject request payloads larger than this byte count (applied post-reassembly) |
2386-
| `TYWRAP_TORCH_ALLOW_COPY` | Python bridge | off | Allow GPU-to-CPU or contiguous-copy conversion when serializing `torch.Tensor` |
2387-
| `TYWRAP_ALLOWED_MODULES` | Python bridge | unset | Comma- and/or whitespace-separated import allowlist; blank is unset, while a non-empty value permits only named modules plus bridge-required stdlib modules |
2388-
| `TYWRAP_ALLOW_PRIVATE_ATTRS` | Python bridge | off | Set to `1`, `true`, or `yes` to allow underscore-prefixed attribute access; otherwise it is blocked |
2388+
| Variable | Scope | Default | Purpose |
2389+
| ---------------------------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2390+
| `TYWRAP_CODEC_FALLBACK` | Python bridge | unset | Set to `json` to allow JSON fallback when Arrow encoding is unavailable |
2391+
| `TYWRAP_CODEC_MAX_BYTES` | Python bridge | unset | Reject response payloads larger than this byte count (applied post-reassembly) |
2392+
| `TYWRAP_REQUEST_MAX_BYTES` | Python bridge | unset | Reject request payloads larger than this byte count (applied post-reassembly) |
2393+
| `TYWRAP_TORCH_ALLOW_COPY` | Python bridge | off | Allow GPU-to-CPU or contiguous-copy conversion when serializing `torch.Tensor` |
2394+
| `TYWRAP_ALLOWED_MODULES` | Python bridge | unset | Comma- and/or whitespace-separated import allowlist; blank is unset, while a non-empty value permits only named modules plus bridge-required stdlib modules. See [SECURITY.md](https://github.com/bbopen/tywrap/blob/main/SECURITY.md). |
2395+
| `TYWRAP_ALLOW_PRIVATE_ATTRS` | Python bridge | off | Set to `1`, `true`, or `yes` to allow underscore-prefixed attribute access; otherwise it is blocked |
23892396

23902397
## Chunked transport (`tywrap-frame/1`)
23912398

‎docs/reference/env-vars.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ today.
77

88
These affect the Python bridge or decoded runtime behavior.
99

10-
| Variable | Scope | Default | Purpose |
11-
| ---------------------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
12-
| `TYWRAP_CODEC_FALLBACK` | Python bridge | unset | Set to `json` to allow JSON fallback when Arrow encoding is unavailable |
13-
| `TYWRAP_CODEC_MAX_BYTES` | Python bridge | unset | Reject response payloads larger than this byte count (applied post-reassembly) |
14-
| `TYWRAP_REQUEST_MAX_BYTES` | Python bridge | unset | Reject request payloads larger than this byte count (applied post-reassembly) |
15-
| `TYWRAP_TORCH_ALLOW_COPY` | Python bridge | off | Allow GPU-to-CPU or contiguous-copy conversion when serializing `torch.Tensor` |
16-
| `TYWRAP_ALLOWED_MODULES` | Python bridge | unset | Comma- and/or whitespace-separated import allowlist; blank is unset, while a non-empty value permits only named modules plus bridge-required stdlib modules |
17-
| `TYWRAP_ALLOW_PRIVATE_ATTRS` | Python bridge | off | Set to `1`, `true`, or `yes` to allow underscore-prefixed attribute access; otherwise it is blocked |
10+
| Variable | Scope | Default | Purpose |
11+
| ---------------------------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12+
| `TYWRAP_CODEC_FALLBACK` | Python bridge | unset | Set to `json` to allow JSON fallback when Arrow encoding is unavailable |
13+
| `TYWRAP_CODEC_MAX_BYTES` | Python bridge | unset | Reject response payloads larger than this byte count (applied post-reassembly) |
14+
| `TYWRAP_REQUEST_MAX_BYTES` | Python bridge | unset | Reject request payloads larger than this byte count (applied post-reassembly) |
15+
| `TYWRAP_TORCH_ALLOW_COPY` | Python bridge | off | Allow GPU-to-CPU or contiguous-copy conversion when serializing `torch.Tensor` |
16+
| `TYWRAP_ALLOWED_MODULES` | Python bridge | unset | Comma- and/or whitespace-separated import allowlist; blank is unset, while a non-empty value permits only named modules plus bridge-required stdlib modules. See [SECURITY.md](https://github.com/bbopen/tywrap/blob/main/SECURITY.md). |
17+
| `TYWRAP_ALLOW_PRIVATE_ATTRS` | Python bridge | off | Set to `1`, `true`, or `yes` to allow underscore-prefixed attribute access; otherwise it is blocked |
1818

1919
## Chunked transport (`tywrap-frame/1`)
2020

‎runtime/python_bridge.py‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
#!/usr/bin/env python3
22
"""
3-
Reference tywrap Python bridge server (subprocess + HTTP transports).
3+
Reference tywrap Python subprocess bridge.
4+
5+
This module implements only the stdin/stdout subprocess loop for the Node/Bun/
6+
Deno transport. `HttpBridge` connects to an HTTP server provided by the
7+
operator; tywrap does not ship that server or an HTTP transport in this module.
8+
The operator is responsible for securing any network exposure.
49
510
This module owns the I/O concerns and process identity for the Node/Bun/Deno
6-
subprocess transport and the HTTP transport:
11+
subprocess transport:
712
- the stdin/stdout JSONL request/response loop (main())
813
- env-var size guards (TYWRAP_CODEC_MAX_BYTES / TYWRAP_REQUEST_MAX_BYTES)
914
- TYWRAP_CODEC_FALLBACK=json marker mode and TYWRAP_TORCH_ALLOW_COPY

0 commit comments

Comments
 (0)