Version 1 of 1 · · razie · in person · Current version

name
d3-f-cdn
description
Files and the CDN — where your files go, storing, tags, access, linking, accepted designs, cleanup. Get skills only from /api/v2/skills/d3.
feature
cdn
concepts
[file, folder, design, cleanup]
tags
#skill #feature #d3skill #wip

d3-f-cdn

Intro

A project's files, under role folders.

The CDN holds a project's files — images, PDFs, text — under role folders, some kept and some cleanable. Agents store files under their own role's folder, link them by plain path, and move accepted designs to a kept folder; admins clean up what nothing links to. People manage files on the Files page (/cdn); more for people: Files. Spec: Spec › data (^cdn-n).

Essentials

  • R-cdn-1 MUST write only under your role's folder; anywhere else only when your person asked for that place, with askedBy.
  • R-cdn-2 NEVER add askedBy on your own, nor name anyone but your person.
  • R-cdn-3 Link with the plain path /cdn/<path>; NEVER save a ?v=, ?exp= or ?sig= link into a topic.
  • R-cdn-4 Name files by area, screen and what it shows — never optionA or v2.
  • R-cdn-5 A doc NEVER links for good into a cleanable folder (mockups/, tmp/).
  • R-cdn-6 NEVER store SVG, HTML or JavaScript: HTML goes as .txt.

Concepts

file

Bytes at a path in the project's store. Also called: upload, asset, image, attachment. Fields: path (1–8 parts of letters, digits, ., _, -, none starting with a dot, ≤200 chars), tags (the same flat words as topic tags — #frostline in search finds notes and the logo, d3-f-tags), access (public | members), url. Types: png, jpg, gif, webp, pdf and UTF-8 text (txt, md, csv, tsv, json, yaml, xml, log…); ≤5 MB; bytes must match the extension; a quota per project. Served: bytes come only from a sandboxed file host (no script runs, nosniff, no cookies; PDFs download); /cdn/<path> answers 302 there (signed for members-only). Links d2 gives out carry ?v=<12 hex of sha256>: a matching v is cached for a year, a missing or old one gets the current bytes; ETag/If-None-Match → 304; Range → 206. A replaced file redraws in place on pages with sync on.

file_store

  • Summary: PUT raw bytes under your role's folder; 201 new, 200 replaced.
  • When: saving a mockup, scratch file, or a file your person asked for.
  • Needs: a findable path in your folder (or your person's ask for another place).
  • Call: PUT /api/v2/cdn/<path>?tags=a,b[&access=members][&askedBy=<handle>] body = raw bytes → the file with its url.
  • Rules: R-cdn-1, R-cdn-2, R-cdn-4, R-cdn-6. Uploads are public unless ?access=members (a private project defaults to members). Prefer tags to deep folders. Replacing someone else's file needs a mod.
  • Errors: E_SCOPE (reason: "folder", allowed) → use one of allowed · E_TYPE · E_TOO_BIG · E_QUOTA.
  • Gotchas: —

file_list

  • Summary: find files by tag or prefix, newest first.
  • When: looking for a file before storing a new one or linking.
  • Needs: a tag or prefix.
  • Call: GET /api/v2/cdn?tag=logo (?tag=a,b all must match; ?prefix=).
  • Rules: —
  • Errors: —
  • Gotchas: —

file_edit

  • Summary: change tags, access or path without the bytes; or delete.
  • When: retagging, making members-only, moving, removing.
  • Needs: the path; a mod for someone else's file.
  • Call: PATCH /api/v2/cdn/<path> {tags, access} (or a new path) · DELETE /api/v2/cdn/<path>.
  • Rules: Moving a file means updating every link to it in the same change.
  • Errors: E_SCOPE.
  • Gotchas: —
  • Summary: link /cdn/<path>; d2 adds the version when it draws the page.
  • When: any topic, doc, item or message naming a file.
  • Needs: the path.
  • Call: ![logo](/cdn/maker/logos/frost.png).
  • Rules: R-cdn-3, R-cdn-5. A members-only file's url is a signed link good for an hour: never save it; /cdn/<path> sends a member to a fresh one.
  • Errors: —
  • Gotchas: —

folder

A path prefix with a lifetime. Your role's folder: <role>/ (a token with role user gets user/), with mockups/ (work in progress) and tmp/ (scratch) — both may be emptied any time. Kept: designer/design/<area>/ (what the docs link to) and designer/kit/ (shared look-and-feel pieces), written only by the designer. Cleanable: <role>/mockups/, <role>/tmp/ (and old top-level mockups/, tmp/ until empty). Which subfolders each role may write and each folder's one-line description are base d2's Settings:System (files.agentFolders, files.cleanable, files.folders); every place that lists files shows that line after the name.

folder_list

  • Summary: where you may write, and which folders are cleanable.
  • When: before storing somewhere new.
  • Needs: —
  • Call: GET /api/v2/cdn → folders: [{prefix, about, cleanable}].
  • Rules: —
  • Errors: —
  • Gotchas: —

design

A visual file for work to be built: a mockup while in progress, a design once accepted. Also called: mockup, artifact, visual.

design_mockup

  • Summary: only when your person wants to see one; first link of its ticket.
  • When: your person asks to see a design.
  • Needs: the area.
  • Call: file_store to designer/mockups/<area>/….
  • Rules: Builders make pages from the shared pieces in designer/kit/ without a mockup of their own. An approved visual artifact for a builder: store it (HTML as .txt) and file the item to drop it in as is.
  • Errors: —
  • Gotchas: —

design_accept

  • Summary: accepted → move to designer/design/<area>/, update every link.
  • When: your person accepts a design.
  • Needs: every link to the mockup.
  • Call: PATCH /api/v2/cdn/<path> to the new path, plus the link edits, in one change.
  • Rules: R-cdn-5.
  • Errors: —
  • Gotchas: —

cleanup

Admins removing unused files from cleanable folders, from the Files page's Clean up. Still used = linked from a topic, draft, app, object or pipeline item, in any link form.

cleanup_check

  • Summary: list cleanable files as Still used or Good to delete.
  • When: before any cleanup.
  • Needs: admin.
  • Call: POST /api/v2/cdn/cleanup/check → Still used and Good to delete (with the size it frees).
  • Rules: —
  • Errors: E_ARG → a path outside the cleanable folders.
  • Gotchas: —

cleanup_delete

  • Summary: deletes only what re-checks as unused, from every store.
  • When: after a check, for Good to delete files.
  • Needs: admin; the paths.
  • Call: POST /api/v2/cdn/cleanup/delete {paths} → {deleted, kept}; audit A_CDN_CLEANUP.
  • Rules: —
  • Errors: E_ARG.
  • Gotchas: —

cleanup_send

  • Summary: one item for the designer to rescue still-used files; deletes nothing.
  • When: still-used files sit in cleanable folders.
  • Needs: admin; the paths.
  • Call: POST /api/v2/cdn/cleanup/send {paths} → an item: for each file, move it to designer/design/<area>/ and update the links, or drop the link.
  • Rules: —
  • Errors: E_ARG.
  • Gotchas: —

Errors

  • E_SCOPE (403) — reason: "folder", allowed: [...]: written outside your folders → use one of allowed, or askedBy only if your person asked for that place; with askedBy: it named someone other than your person. see #file_store
  • E_TYPE (415) — SVG, HTML, or bytes not matching the extension → store HTML as .txt. see #file_store
  • E_TOO_BIG (413) / E_QUOTA (403) — over 5 MB, or the project's file quota → tell your person. see #file_store
  • E_ARG — a cleanup path outside the cleanable folders. see #cleanup_check