Files
marqdo/ext/data/storage.mq.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

176 lines
7.5 KiB
Markdown
Executable File

---
markup: occlusion
title: ext/data/storage
description: Object storage Resource (ADR 0007).
import:
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
table: lib/table.mq.md
---
Use this resource for explicitly configured storage URLs; use lib/fs.mq.md for ordinary rooted filesystem operations. [The data entry](index.mq.md) explains resource ownership and the native web dependency. File bodies and byte encodings follow the native storage contract, so callers must inspect the returned operation result before publishing a resource URL. Add backend support in the existing plugin rather than encoding transport logic in callers.
## _load
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the native web plugin before resource operations; missing binaries stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="web"))**.
1. `p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
We **[Print the prepared message](print(text="ext/data: native web plugin not found"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
Return *None*.
# storage
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | any | "file:data/blobs" | Resource connection URL; scheme selects the documented backend |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Object storage. `file:dir` stores blobs on disk (offline / gold). `s3://bucket?endpoint=http://127.0.0.1:9000&access_key=…&secret_key=…` talks to MinIO / S3. |
Use `url`="file:data/blobs" as the inputs for this operation.
Object storage. `file:dir` stores blobs on disk (offline / gold). `s3://bucket?endpoint=http://127.0.0.1:9000&access_key=…&secret_key=…` talks to MinIO / S3.
We **[Load the native plugin required by this operation](_load())**.
Return *[Object storage. file:dir stores blobs on disk (offline / gold). s3://bucket?endpoint=http://127.0.0.1:9000&access_key=…&secret_key=… talks to MinIO / S3.](web_storage_new(url=`url`))*.
## put
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| body | any | None | Object or request content, as described by the operation |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| content_type | any | "application/octet-stream" | MIME type associated with the supplied content |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Provide either `body` (text) or `path` (local file to upload). |
Use `key`, `body`=None, `path`=None, `content_type`="application/octet-stream" as the inputs for this operation.
Provide either `body` (text) or `path` (local file to upload).
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Provide either body (text) or path (local file to upload).](web_storage_put(url=`url`, key=`key`, body=`body`, path=`path`, content_type=`content_type`))*.
## get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read the object selected by its storage key and retain the backend result shape. |
Use `key` as the inputs for this operation.
Read the object selected by its storage key and retain the backend result shape.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Read the object selected by its storage key and retain the backend result shape.](web_storage_get(url=`url`, key=`key`))*.
## delete
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | any | required | Entry or field key within the selected resource |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delete the selected object from this storage resource. |
Use `key` as the inputs for this operation.
Delete the selected object from this storage resource.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[Delete the selected object from this storage resource.](web_storage_delete(url=`url`, key=`key`))*.
## list
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prefix | any | "" | Object-key or generated-name prefix |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List object entries under the supplied key prefix. |
Use `prefix`="" as the inputs for this operation.
List object entries under the supplied key prefix.
We retain **`url` = [Read url field](access(`self`, "url"))**.
Return *[List object entries under the supplied key prefix.](web_storage_list(url=`url`, prefix=`prefix`))*.
# media
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| storage | any | None | Storage resource created by the public storage constructor |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Offline helpers for upload validation and saving into `# storage` (also used by HTTP `app.upload`). |
Use `storage`=None as the inputs for this operation.
Offline helpers for upload validation and saving into `# storage` (also used by HTTP `app.upload`).
We **[Load the native plugin required by this operation](_load())**.
Return *[Offline helpers for upload validation and saving into # storage (also used by HTTP app.upload).](web_media_new(storage=`storage`))*.
## validate
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| filename | any | required | Original or suggested filename |
| content_type | any | "application/octet-stream" | MIME type associated with the supplied content |
| size | any | required | Byte size checked by upload validation |
| max_bytes | any | 5242880 | Maximum accepted byte count; exceeding the limit must fail explicitly |
| types | any | None | Allowed MIME types for upload validation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Validate an upload filename, MIME type and byte size against explicit limits before storing anything. |
Use `filename`, `content_type`="application/octet-stream", `size`, `max_bytes`=5242880, `types`=None as the inputs for this operation.
Validate an upload filename, MIME type and byte size against explicit limits before storing anything.
Return *[Validate an upload filename, MIME type and byte size against explicit limits before storing anything.](web_upload_validate(filename=`filename`, content_type=`content_type`, size=`size`, max_bytes=`max_bytes`, types=`types`))*.
## save
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| key | any | None | Entry or field key within the selected resource |
| content_type | any | "application/octet-stream" | MIME type associated with the supplied content |
| prefix | any | "uploads/" | Object-key or generated-name prefix |
| storage | any | None | Storage resource created by the public storage constructor |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Save the selected local upload through the configured storage resource and return its storage result. |
Use `path`, `key`=None, `content_type`="application/octet-stream", `prefix`="uploads/", `storage`=None as the inputs for this operation.
We retain **st = storage**.
1. `st` == None
We retain **`st` = [Read storage field](access(`self`, "storage"))**.
2. *
Return *[Save the selected local upload through the configured storage resource and return its storage result.](web_upload_save(storage=`st`, path=`path`, key=`key`, content_type=`content_type`, prefix=`prefix`))*.