feat(supabase): R5.5 upload-sheet-assets in Rust, R5.4 caps and FLOOR clarification

Core rules curation::upload (manifest, local destination, bytes through the SVG reader,
plan from observed state); binary upload-sheet-assets over ureq (handshake, no overwrite,
confirm after verify, bounded retries, key never printed); pnpm assets:upload repointed,
e2e:sheet-assets for the local stack. 4 MiB cap on changes.json and references.json.
FLOOR clarification for audit prose with its negative proof.
This commit is contained in:
bchanot committed 2026-10-23 21:15:22 +02:00
1 parent 637ea6334c
commit 2c445063a4
20 files changed
+1595 -21

No files matched your search

+29 -10
View File
@@ -17,10 +17,11 @@
#![allow(clippy::disallowed_methods)]
use std::fs::OpenOptions;
use std::io::Write;
use std::io::{Read, Write};
use std::path::{Component, Path, PathBuf};
use std::{env, fs, process};
use faunosteo_core::curation::draft::schema::MAX_CURATION_FILE_BYTES;
use faunosteo_core::curation::draft::svg_compare::{TriggerNames, compare_drawing};
use faunosteo_core::curation::draft::{
DraftInput, build_equine_draft, parse_changeset, parse_references, parse_view_box,
@@ -60,11 +61,21 @@ struct Folder {
/// 1.1 MB): a resource cap on what the tool reads.
const MAX_FILE_BYTES: u64 = 16 * 1024 * 1024;
/// The cap of an authored curation file, the core's own (`MAX_CURATION_FILE_BYTES`): the file
/// is never read beyond it, so a larger one is refused before the allocation.
const MAX_CURATION_BYTES: u64 = MAX_CURATION_FILE_BYTES as u64;
/// A regular file of the seed folder, read under the cap: its canonical path (every symbolic
/// link resolved, folders included) must lie in the canonical seed folder, so a link never
/// leads a read outside it; devices and pipes are refused. The repository is a single user's
/// working copy: a swap between the check and the read is not defended (RUST.md §11.13).
fn read(path: &Path) -> Result<Vec<u8>, String> {
read_capped(path, MAX_FILE_BYTES)
}
/// `read` under a given cap, enforced on the bytes actually read as well as on the size seen
/// first, so a file that grows between the two is still refused before it is held.
fn read_capped(path: &Path, cap: u64) -> Result<Vec<u8>, String> {
let refuse = |why: &str| format!("{}: {why}", path.display());
let seed = fs::canonicalize(SEED).map_err(|error| format!("{SEED}: {error}"))?;
let canonical = fs::canonicalize(path).map_err(|error| refuse(&error.to_string()))?;
@@ -75,16 +86,24 @@ fn read(path: &Path) -> Result<Vec<u8>, String> {
if !metadata.file_type().is_file() {
return Err(refuse("not a regular file"));
}
if metadata.len() > MAX_FILE_BYTES {
return Err(refuse(&format!("larger than {MAX_FILE_BYTES} bytes")));
if metadata.len() > cap {
return Err(refuse(&format!("larger than {cap} bytes")));
}
fs::read(&canonical).map_err(|error| refuse(&error.to_string()))
let mut bytes = Vec::new();
let file = fs::File::open(&canonical).map_err(|error| refuse(&error.to_string()))?;
file.take(cap + 1)
.read_to_end(&mut bytes)
.map_err(|error| refuse(&error.to_string()))?;
if bytes.len() as u64 > cap {
return Err(refuse(&format!("larger than {cap} bytes")));
}
Ok(bytes)
}
/// `readFile(path, 'utf8')`: invalid UTF-8 becomes U+FFFD, as the TypeScript read the
/// curation files.
fn read_text(path: &Path) -> Result<String, String> {
Ok(String::from_utf8_lossy(&read(path)?).into_owned())
/// `readFile(path, 'utf8')` of an authored curation file, under the 4 MiB curation cap: invalid
/// UTF-8 becomes U+FFFD, as the TypeScript read them.
fn read_curation_text(path: &Path) -> Result<String, String> {
Ok(String::from_utf8_lossy(&read_capped(path, MAX_CURATION_BYTES)?).into_owned())
}
fn svg(name: &str) -> Result<SvgSource, String> {
@@ -128,9 +147,9 @@ fn legacy_folder(input: &EquineLegacyInput, result: &ImportResult) -> Result<Fol
/// `draft/`: the R5.3 texts, then the frozen cleaned drawing (read, never re-cleaned).
fn draft_folder(result: &ImportResult) -> Result<Folder, String> {
let curation = Path::new(SEED).join("curation");
let references = parse_references(&read_text(&curation.join("references.json"))?)
let references = parse_references(&read_curation_text(&curation.join("references.json"))?)
.map_err(|error| error.to_string())?;
let changeset = parse_changeset(&read_text(&curation.join("changes.json"))?)
let changeset = parse_changeset(&read_curation_text(&curation.join("changes.json"))?)
.map_err(|error| error.to_string())?;
let cleaned_svg = read(&Path::new(SEED).join(DRAFT_FOLDER).join(CLEANED_ASSET))?;
let head = result.view_boxes.get(HEAD_VIEW_ID).and_then(|v| v.as_str());
@@ -0,0 +1,214 @@
//! `upload-sheet-assets` (R5.5): uploads the SVG drawings of a generated sheet seed folder to
//! the private Storage bucket `anatomical-sheet-assets` of a LOCAL Supabase stack, content
//! addressed (`<sha256>.svg`), and confirms each asset row once its object is verified.
//!
//! upload-sheet-assets --check <seed folder> read-only: verify the files, the destination
//! and what is already there; write nothing
//! upload-sheet-assets <seed folder> the same, then upload and confirm what is missing
//!
//! Environment: `SUPABASE_URL` (a local stack: loopback, or the DEV address
//! `FAUNOSTEO_DEV_HOST`; `http` with an explicit port; no default) and
//! `SUPABASE_SERVICE_ROLE_KEY` (never printed). The folder lies under
//! `supabase/seed/anatomical-sheets`; a relative path is typed from the folder pnpm was run in
//! (`INIT_CWD`), else the current one.
//!
//! Order of a run: files and manifest checked, destination checked, handshake, then every
//! entry planned from the state found; any refusal stops the run before the first write. An
//! object that exists is read back and compared with its key, never replaced; an asset row is
//! confirmed only after its object is verified. A rerun after a failure resumes safely.
//! Like `import-equine`, this tool owns the file system, the environment and the network; the
//! rules are the core's (`curation::upload`).
#![allow(clippy::disallowed_methods)]
mod storage;
use std::io::Read;
use std::path::{Path, PathBuf};
use std::{env, fs, process};
use faunosteo_core::curation::upload::{
AssetEntry, MAX_ASSET_BYTES, MAX_MANIFEST_BYTES, ObjectState, Plan, UploadError, UploadKind,
check_destination, parse_manifest, plan_entry, refuse, verify_asset,
};
use storage::{Secret, Storage};
const SEED_ROOT: &str = concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../supabase/seed/anatomical-sheets"
);
/// A local entry whose bytes passed `verify_asset`.
struct Local {
entry: AssetEntry,
bytes: Vec<u8>,
}
/// A regular file under `root` (every link resolved), read under a cap: a file that grows
/// between the size check and the read is still refused. The seed is a single user's working
/// copy: a swap between the check and the read is not defended.
fn read_confined(path: &Path, root: &Path, cap: usize) -> Result<Vec<u8>, UploadError> {
let bad = |why: &str| refuse(UploadKind::Content, format!("{}: {why}", path.display()));
let canonical = fs::canonicalize(path).map_err(|e| bad(&e.to_string()))?;
if !canonical.starts_with(root) {
return Err(bad("leads outside the seed folder"));
}
let metadata = fs::metadata(&canonical).map_err(|e| bad(&e.to_string()))?;
if !metadata.is_file() || metadata.len() > cap as u64 {
return Err(bad("not a regular file, or too large"));
}
let mut bytes = Vec::new();
let file = fs::File::open(&canonical).map_err(|e| bad(&e.to_string()))?;
file.take(cap as u64 + 1)
.read_to_end(&mut bytes)
.map_err(|e| bad(&e.to_string()))?;
if bytes.len() > cap {
return Err(bad("too large"));
}
Ok(bytes)
}
/// The folder typed on the command line: from `INIT_CWD` when pnpm set it, canonical, a
/// directory, inside the seed root.
fn resolve_folder(typed: &str) -> Result<PathBuf, UploadError> {
let bad = |why: &str| refuse(UploadKind::Content, format!("{typed}: {why}"));
let base = env::var_os("INIT_CWD")
.map(PathBuf::from)
.filter(|p| p.is_absolute())
.map_or_else(env::current_dir, Ok)
.map_err(|e| bad(&e.to_string()))?;
let folder = fs::canonicalize(base.join(typed)).map_err(|e| bad(&e.to_string()))?;
let root = fs::canonicalize(SEED_ROOT).map_err(|e| bad(&e.to_string()))?;
if !folder.starts_with(&root) || !folder.is_dir() {
return Err(bad("not a folder under supabase/seed/anatomical-sheets"));
}
Ok(folder)
}
/// Manifest, then every drawing, all verified before any request is made.
fn load_local(folder: &Path) -> Result<Vec<Local>, UploadError> {
let manifest = read_confined(&folder.join("assets.json"), folder, MAX_MANIFEST_BYTES)?;
let text = String::from_utf8(manifest)
.map_err(|_| refuse(UploadKind::Manifest, "assets.json is not UTF-8"))?;
parse_manifest(&text)?
.into_iter()
.map(|entry| {
let path = folder.join("assets").join(&entry.file);
let bytes = read_confined(&path, folder, MAX_ASSET_BYTES)?;
verify_asset(&entry, &bytes)?;
Ok(Local { entry, bytes })
})
.collect()
}
fn required_env(name: &str) -> Result<String, UploadError> {
env::var(name)
.ok()
.filter(|value| !value.is_empty())
.ok_or_else(|| refuse(UploadKind::Destination, format!("{name} is required")))
}
fn connect() -> Result<Storage, UploadError> {
let dev_host = env::var("FAUNOSTEO_DEV_HOST").ok();
let destination = check_destination(&required_env("SUPABASE_URL")?, dev_host.as_deref())?;
let key = Secret::new(required_env("SUPABASE_SERVICE_ROLE_KEY")?);
Ok(Storage::new(&destination, key))
}
/// What the destination holds for each entry and the steps that follow; refuses on the first
/// entry that cannot be planned, so nothing is written for a run that cannot complete.
fn plan_all(storage: &Storage, locals: &[Local]) -> Result<Vec<(Plan, ObjectState)>, UploadError> {
locals
.iter()
.map(|local| {
let object = storage.object_state(&local.entry)?;
let row = storage.row_state(&local.entry)?;
Ok((plan_entry(&local.entry, &object, &row)?, object))
})
.collect()
}
fn describe(local: &Local, plan: Plan, check: bool) -> String {
let steps: Vec<&str> = match (plan.upload, plan.confirm) {
(false, false) => vec!["object verified, row confirmed, nothing to do"],
(true, true) => vec!["upload", "confirm"],
(true, false) => vec!["upload"],
(false, true) => vec!["object verified", "confirm"],
};
let verb = if check { "would" } else { "will" };
format!(
"{} {}: {verb} {}",
local.entry.file,
local.entry.object_key(),
steps.join(", ")
)
}
/// Uploads (if absent), verifies the object by reading it back, then confirms (if pending).
fn apply(storage: &Storage, local: &Local, plan: Plan) -> Result<(), UploadError> {
if plan.upload {
storage.upload(&local.entry, &local.bytes)?;
}
if storage.object_state(&local.entry)? != ObjectState::Verified {
return Err(refuse(
UploadKind::State,
format!(
"{}: the object is not the expected bytes after upload",
local.entry.file
),
));
}
if plan.confirm {
storage.confirm(&local.entry)?;
}
Ok(())
}
fn run(args: &[String]) -> Result<(), UploadError> {
let (check, folder) = match args {
[flag, folder] if flag == "--check" => (true, folder),
[folder] if folder != "--check" => (false, folder),
_ => {
return Err(refuse(
UploadKind::Content,
"usage: upload-sheet-assets [--check] <seed folder>",
));
}
};
let locals = load_local(&resolve_folder(folder)?)?;
let storage = connect()?;
storage.handshake()?;
let plans = plan_all(&storage, &locals)?;
for (local, (plan, _)) in locals.iter().zip(&plans) {
println!("{}", describe(local, *plan, check));
}
if check {
return Ok(());
}
for (local, (plan, _)) in locals.iter().zip(&plans) {
apply(&storage, local, *plan)?;
println!("{} done", local.entry.file);
}
Ok(())
}
fn main() {
let args: Option<Vec<String>> = env::args_os()
.skip(1)
.map(|a| a.into_string().ok())
.collect();
let Some(args) = args else {
eprintln!("an argument is not valid UTF-8");
process::exit(2);
};
match run(&args) {
Ok(()) => println!("ok"),
Err(error) => {
eprintln!("refused: {error}");
process::exit(if error.kind == UploadKind::Network {
3
} else {
1
});
}
}
}
@@ -0,0 +1,248 @@
//! The destination, over HTTP: Storage objects and the asset rows of a local Supabase stack,
//! with the service key. Every status is classified into the closed `UploadKind`s; the key is
//! held in a `Secret` and goes in two request headers, nowhere else.
use std::time::Duration;
use faunosteo_core::curation::ids::sha256_hex;
use faunosteo_core::curation::upload::{
AssetEntry, BUCKET, Destination, MAX_ASSET_BYTES, ObjectState, RowState, UploadError,
UploadKind, refuse,
};
use serde_json::{Value, json};
use ureq::Agent;
const MAX_BODY: u64 = 1024 * 1024;
const ATTEMPTS: u32 = 3;
/// A key that never prints: `Debug` hides it and there is no `Display`.
pub struct Secret(String);
impl Secret {
pub fn new(text: String) -> Self {
Self(text)
}
}
impl std::fmt::Debug for Secret {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("Secret(<redacted>)")
}
}
/// What an HTTP exchange gave back: the status and the (capped) body.
struct Reply {
status: u16,
body: Vec<u8>,
}
pub struct Storage {
agent: Agent,
origin: String,
key: Secret,
}
impl Storage {
pub fn new(destination: &Destination, key: Secret) -> Self {
let agent: Agent = Agent::config_builder()
.timeout_global(Some(Duration::from_secs(30)))
.timeout_connect(Some(Duration::from_secs(5)))
.max_redirects(0)
// The service key never goes through a proxy picked up from the environment.
.proxy(None)
.http_status_as_error(false)
.user_agent("faunosteo-upload-sheet-assets")
.build()
.into();
Self {
agent,
origin: destination.origin().to_owned(),
key,
}
}
/// One exchange, retried on a transport error or a 5xx only (a refusal is final). The
/// request is built again on each attempt.
fn exchange(
&self,
limit: u64,
send: impl Fn(&Agent, &Self) -> Result<ureq::http::Response<ureq::Body>, ureq::Error>,
) -> Result<Reply, UploadError> {
let mut last = refuse(UploadKind::Network, "no attempt made");
for attempt in 1..=ATTEMPTS {
if attempt > 1 {
std::thread::sleep(Duration::from_millis(500 * u64::from(attempt)));
}
match send(&self.agent, self).and_then(|mut response| read_reply(&mut response, limit))
{
Ok(reply) if reply.status < 500 => return Ok(reply),
Ok(reply) => last = refuse(UploadKind::Network, format!("HTTP {}", reply.status)),
Err(error) => last = refuse(UploadKind::Network, error.to_string()),
}
}
Err(last)
}
fn authorised<B>(&self, request: ureq::RequestBuilder<B>) -> ureq::RequestBuilder<B> {
request
.header("apikey", &self.key.0)
.header("Authorization", &format!("Bearer {}", self.key.0))
}
fn object_url(&self, entry: &AssetEntry) -> String {
format!(
"{}/storage/v1/object/{BUCKET}/{}",
self.origin,
entry.object_key()
)
}
/// The destination is the local Faunosteo stack: the sheet bucket exists and is private,
/// and the key is accepted. Nothing is written.
pub fn handshake(&self) -> Result<(), UploadError> {
let url = format!("{}/storage/v1/bucket/{BUCKET}", self.origin);
let reply = self.exchange(MAX_BODY, |agent, me| me.authorised(agent.get(&url)).call())?;
check_access(&reply)?;
let bucket: Value = serde_json::from_slice(&reply.body)
.map_err(|_| refuse(UploadKind::Handshake, "the bucket answer is not JSON"))?;
let name = bucket.get("name").and_then(Value::as_str);
let public = bucket.get("public").and_then(Value::as_bool);
if reply.status != 200 || name != Some(BUCKET) || public != Some(false) {
return Err(refuse(
UploadKind::Handshake,
format!("{BUCKET} is missing, or not a private bucket"),
));
}
Ok(())
}
/// Absent, or present with bytes that hash to the key, or present with other bytes.
pub fn object_state(&self, entry: &AssetEntry) -> Result<ObjectState, UploadError> {
let url = self.object_url(entry);
let limit = MAX_ASSET_BYTES as u64 + 1;
let reply = self.exchange(limit, |agent, me| me.authorised(agent.get(&url)).call())?;
if is_not_found(&reply) {
return Ok(ObjectState::Absent);
}
check_access(&reply)?;
expect_status(&reply, 200, "object read")?;
let found = sha256_hex(&reply.body);
Ok(if found == entry.sha256 {
ObjectState::Verified
} else {
ObjectState::Different(found)
})
}
/// Creates the object; an existing key is never replaced (`x-upsert: false`). Returns
/// whether this call created it.
pub fn upload(&self, entry: &AssetEntry, bytes: &[u8]) -> Result<bool, UploadError> {
let url = self.object_url(entry);
let reply = self.exchange(MAX_BODY, |agent, me| {
me.authorised(agent.post(&url))
.header("Content-Type", "image/svg+xml")
.header("x-upsert", "false")
.send(bytes)
})?;
check_access(&reply)?;
if is_duplicate(&reply) {
return Ok(false);
}
expect_status(&reply, 200, "upload")?;
Ok(true)
}
/// The row of the asset: absent, another hash, pending or confirmed.
pub fn row_state(&self, entry: &AssetEntry) -> Result<RowState, UploadError> {
let url = format!(
"{}/rest/v1/anatomical_sheet_assets?id=eq.{}&select=sha256,uploaded_at",
self.origin, entry.svg_asset_id
);
let reply = self.exchange(MAX_BODY, |agent, me| me.authorised(agent.get(&url)).call())?;
check_access(&reply)?;
expect_status(&reply, 200, "row read")?;
let rows: Vec<Value> = serde_json::from_slice(&reply.body)
.map_err(|_| refuse(UploadKind::Handshake, "the row answer is not a JSON list"))?;
Ok(match rows.first() {
None => RowState::Unknown,
Some(row) => row_state_of(row, &entry.sha256),
})
}
/// Marks the asset bytes as present (idempotent on the server, service role only).
pub fn confirm(&self, entry: &AssetEntry) -> Result<(), UploadError> {
let url = format!("{}/rest/v1/rpc/confirm_sheet_asset_upload", self.origin);
let body = json!({ "asset_id": entry.svg_asset_id });
let reply = self.exchange(MAX_BODY, |agent, me| {
me.authorised(agent.post(&url)).send_json(&body)
})?;
check_access(&reply)?;
expect_status(&reply, 200, "confirm")
}
}
fn row_state_of(row: &Value, expected_sha256: &str) -> RowState {
let found = row
.get("sha256")
.and_then(Value::as_str)
.unwrap_or_default();
if found != expected_sha256 {
return RowState::OtherHash(found.to_owned());
}
match row.get("uploaded_at") {
Some(Value::Null) | None => RowState::Pending,
Some(_) => RowState::Confirmed,
}
}
fn read_reply(
response: &mut ureq::http::Response<ureq::Body>,
limit: u64,
) -> Result<Reply, ureq::Error> {
let body = response
.body_mut()
.with_config()
.limit(limit)
.read_to_vec()?;
Ok(Reply {
status: response.status().as_u16(),
body,
})
}
/// The `statusCode` of a Storage error body (a string, "404" or "409" here).
fn storage_code(reply: &Reply) -> Option<String> {
let body: Value = serde_json::from_slice(&reply.body).ok()?;
body.get("statusCode")?.as_str().map(str::to_owned)
}
/// Storage answers a missing object with HTTP 400 and `statusCode` "404" in this image family.
fn is_not_found(reply: &Reply) -> bool {
reply.status == 404 || (reply.status == 400 && storage_code(reply).as_deref() == Some("404"))
}
/// A key that already exists answers 409, or 400 with `statusCode` "409" ("Duplicate").
fn is_duplicate(reply: &Reply) -> bool {
reply.status == 409 || (reply.status == 400 && storage_code(reply).as_deref() == Some("409"))
}
fn check_access(reply: &Reply) -> Result<(), UploadError> {
if matches!(reply.status, 401 | 403) {
return Err(refuse(
UploadKind::Access,
format!("HTTP {}: the destination refused the key", reply.status),
));
}
Ok(())
}
fn expect_status(reply: &Reply, wanted: u16, what: &str) -> Result<(), UploadError> {
if reply.status == wanted {
return Ok(());
}
// The server's free text is not echoed: only the step and the status.
Err(refuse(
UploadKind::Handshake,
format!("{what}: unexpected HTTP {}", reply.status),
))
}