- 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。
176 lines
7.5 KiB
Markdown
Executable File
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`))*.
|