- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
13 KiB
Executable File
markup, import, title, description
| markup | import | title | description | ||||
|---|---|---|---|---|---|---|---|
| occlusion |
|
lib/net | English HTTP(S) wrappers. Optional headers / content_type via host aliases. |
English HTTP(S) wrappers. Optional headers / content_type via host aliases.
Use HTTP, response parsing and bounded downloads.
Behavior and limits: get requires network.read; configurable request conservatively requires network.write because its method is dynamic. request/get return Result with response headers; legacy http_* retain their historical contracts. Downloads also require fs.write.
This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.
Implementation: src/host/net.rs、src/host/net_ops.rs
For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.
http_get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | HTTPS supported |
Use url, headers=None as the inputs for this operation.
Effects: network.read.
HTTPS supported. Optional named arg headers= (map). Responses are capped at 8 MiB before decoding, so an upstream cannot exhaust the interpreter's memory.
Return [HTTPS supported](> host_http_get url=url headers=headers).
http_post
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| body | any | required | Request body, or replacement text for document operations |
| content_type | any | None | HTTP content type override; None uses the helper default |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Default content type is JSON |
Use url, body, content_type=None, headers=None as the inputs for this operation.
Effects: network.write.
Default content type is JSON. Optional content_type= / headers= (map).
Return [Default content type is JSON](> host_http_post url=url body=body content_type=content_type headers=headers).
http_post_sse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| body | any | required | Request body, or replacement text for document operations |
| content_type | any | None | HTTP content type override; None uses the helper default |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| echo | bool | False | Whether to print streamed SSE text as it arrives |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | POST and consume OpenAI-compatible SSE |
Use url, body, content_type=None, headers=None, echo=False as the inputs for this operation.
Effects: network.write.
POST and consume OpenAI-compatible SSE. Returns {status, events} where events is a list of {type, …} maps (delta / done / error). Optional echo=True prints delta text to stdout as chunks arrive.
Return [POST and consume OpenAI-compatible SSE](> host_http_post_sse url=url body=body content_type=content_type headers=headers echo=echo).
openai_sse_parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| echo | bool | False | Whether to print streamed SSE text as it arrives |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Offline: parse an OpenAI chat SSE body into the same event list (no network) |
Use text, echo=False as the inputs for this operation.
Effects: pure.
Offline: parse an OpenAI chat SSE body into the same event list (no network).
Return [Offline: parse an OpenAI chat SSE body into the same event list (no network)](> host_openai_sse_parse text=text echo=echo).
http_request
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| method | text | required | HTTP method, for example GET or POST |
| url | text | required | Target URL; HTTP helpers accept http or https |
| body | any | None | Request body, or replacement text for document operations |
| content_type | any | None | HTTP content type override; None uses the helper default |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Optional body= / content_type= / headers= |
Use method, url, body=None, content_type=None, headers=None as the inputs for this operation.
Effects: network.write.
Optional body= / content_type= / headers=.
Return [Optional body= / content_type= / headers=](> host_http_request method=method url=url body=body content_type=content_type headers=headers).
url_encode
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Percent-encode a URL segment |
Use text as the inputs for this operation.
Effects: pure.
Percent-encode a URL segment. Spaces become %20 (not form/query +), so literal + remains unambiguous in paths.
Return [Percent-encode a URL segment](> host_url_encode text=text).
cookie_parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| is_response | any | False | Whether to parse a response header block rather than a request |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Parse a Cookie request header (default) or one or more Set-Cookie response headers (is_response=True) into a list of {name, value, path, domain, expires, max_age, secure, http_only, same_site} |
Use text, is_response=False as the inputs for this operation.
Effects: pure.
Call this function directly:
marqdo call lib/net.mq.md cookie_parse 'text="a=1; b=2"' --effects none --json
Parse a Cookie request header (default) or one or more Set-Cookie response headers (is_response=True) into a list of {name, value, path, domain, expires, max_age, secure, http_only, same_site}.
Return [Parse a Cookie request header (default) or one or more Set-Cookie response headers (is_response=True) into a list of {name, value, path, domain, expires, max_age, secure,](> host_cookie_parse text=text is_response=is_response).
multipart_parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| body | any | required | Request body, or replacement text for document operations |
| boundary | any | required | Multipart delimiter from the Content-Type header |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | Parse a multipart/form-data request body (given its boundary) into a list of {name, filename?, content_type?, value} parts |
Use body, boundary as the inputs for this operation.
Effects: pure.
Parse a multipart/form-data request body (given its boundary) into a list of {name, filename?, content_type?, value} parts.
Return [Parse a multipart/form-data request body (given its boundary) into a list of {name, filename?, content_type?, value} parts](> host_multipart_parse body=body boundary=boundary).
markdown_parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Parse Markdown / GFM into HTML (pure transform, no network I/O) |
Use text as the inputs for this operation.
Effects: pure.
Parse Markdown / GFM into HTML (pure transform, no network I/O).
Return [Parse Markdown / GFM into HTML (pure transform, no network I/O)](> host_markdown_parse text=text).
request
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| method | text | required | HTTP method, for example GET or POST |
| url | text | required | Target URL; HTTP helpers accept http or https |
| body | any | None | Request body, or replacement text for document operations |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| timeout_ms | number | 30000 | Timeout in milliseconds; inspect the operation result after waiting |
| max_bytes | number | 8388608 | Maximum bytes read or expanded; exceeding it fails |
| response | text | "text" | Response body representation: text or bytes |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Return Result; value has status, headers and body |
Use method, url, body=None, headers=None, timeout_ms=30000, max_bytes=8388608, response="text" as the inputs for this operation.
Effects: network.write.
Body is text, a bytes record or None; serialize JSON with json.stringify first. Request headers are a map; response headers are name/values records. Output options and destinations are checked before network IO.
Return Result; value has status, headers and body. Timeout is milliseconds; response is text or bytes; headers are name/values records. HTTP error status is a valid response; transport failure is an error.
Return [Body is text, a bytes record or None; serialize JSON with json.stringify first](> host_http_request_result method=method url=url body=body headers=headers timeout_ms=timeout_ms max_bytes=max_bytes response=response).
download
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| path | text | required | Path within the granted filesystem root |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| timeout_ms | number | 30000 | Timeout in milliseconds; inspect the operation result after waiting |
| max_bytes | number | 67108864 | Maximum bytes read or expanded; exceeding it fails |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Bounded streaming download; atomically replace destination only on successful status and complete transfer |
Use url, path, headers=None, timeout_ms=30000, max_bytes=67108864 as the inputs for this operation.
Effects: fs.write,network.read.
Bounded streaming download; atomically replace destination only on successful status and complete transfer. Result value has status/headers/size/path; requires network.read and fs.write.
Return [Bounded streaming download; atomically replace destination only on successful status and complete transfer](> host_http_download url=url path=path headers=headers timeout_ms=timeout_ms max_bytes=max_bytes).
get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| headers | any | None | HTTP header name/value record; None sends no extra headers |
| timeout_ms | number | 30000 | Timeout in milliseconds; inspect the operation result after waiting |
| max_bytes | number | 8388608 | Maximum bytes read or expanded; exceeding it fails |
| response | text | "text" | Response body representation: text or bytes |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Read-only GET as Result, requiring only network |
Use url, headers=None, timeout_ms=30000, max_bytes=8388608, response="text" as the inputs for this operation.
Effects: network.read.
Read-only GET as Result, requiring only network.read. Headers are name/values records; response is text or bytes.
Return [Read-only GET as Result, requiring only network.read](> host_http_get_result url=url headers=headers timeout_ms=timeout_ms max_bytes=max_bytes response=response).
header_values
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| headers | list | required | headers records from a response |
| name | text | required | Header name |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | All values for the header |
Use headers, name as the inputs for this operation.
Effects: pure.
Return all values for a case-insensitive response header; missing yields an empty list. Request headers remain a map; response headers use records to preserve arbitrary names and repeated values.
We retain lower = To lower.
We retain matches = [Where](table.where(list=headers, key="name", value=lower)).
We retain values = [Pluck](table.pluck(list=matches, key="values")).
Return Flatten.