- 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。
296 lines
13 KiB
Markdown
Executable File
296 lines
13 KiB
Markdown
Executable File
---
|
|
markup: occlusion
|
|
import:
|
|
table: lib/table.mq.md
|
|
text: lib/text.mq.md
|
|
title: lib/net
|
|
description: 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.rs)、[src/host/net_ops.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:
|
|
|
|
```sh
|
|
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](text.to_lower(text=`name`))**.
|
|
We retain **`matches` = [Where](table.where(list=`headers`, key="name", value=`lower`))**.
|
|
We retain **`values` = [Pluck](table.pluck(list=`matches`, key="values"))**.
|
|
Return *[Flatten](table.flatten(list=`values`))*.
|