Files

T

Mike-Solar b36cbd6b6f refactor: purge CHandle from module internals (M14 R5)

Module-internal object references are Rust types now (values, Arc,
Mutex); CHandle remains only at the oakengine C-ABI boundary:

- oakundo: the global stack holds UndoStack/UndoCommand values
  directly (stack token is the static's address)
- oaktimeline: marker/workarea boxes carry Arc<Mutex<T>>; commands
  share the same allocation through Arc clones (readers in oakengine
  stubs and the app's graphops updated to lock)
- oaktask/oakstorage: sessions, write-through bindings and the
  database backend pass ProjectArc; the Session drops its manual
  release bookkeeping; nodeutil keeps the CHandle<->Arc boundary
  conversion (release_project restored for the app)
- oakcodec: handle.rs deleted outright (no facade entry needed it);
  texture/block placeholders are unit structs
- oakrender: copier's project handle is an identity u64; alive-count
  machinery removed; handle.rs is make_owned/get/get_mut only
- oakplugin: the instance registry is gone (its unregister key never
  matched, leaking weak entries); handle.rs is the RefBox boundary type
- oaknode/oakcommon: only dead guard/borrow helpers removed; external
  payload handles (texture/processor) documented as the boundary

Flake hunts landed along the way: the audio recording test serializes
on the shared manager lock with a normalized state; the autocacher
cancel test uses a slow producer so cancellation is deterministic.

2026-08-17 16:40:15 +08:00

src

refactor: purge CHandle from module internals (M14 R5)

2026-08-17 16:40:15 +08:00

tests

refactor: purge CHandle from module internals (M14 R5)

2026-08-17 16:40:15 +08:00

Cargo.lock

refactor(crates): implement std::error::Error for all module error enums

2026-08-14 05:45:05 +08:00

Cargo.toml

refactor: sink facade glue into modules (M14 R1)

2026-08-16 20:37:45 +08:00

README.md

refactor: purge CHandle from module internals (M14 R5)

2026-08-17 16:40:15 +08:00

README.md

oakstorage Rust crate — project persistence

Status: implemented (file backends). Manual: docs/zh/plans/riir/M10-oakstorage.md.

Scope

Project persistence — the single module that knows where projects come from and where they are saved to. Backends are pluggable via a manual vtable; shipping in this pass: ove-xml (the XML project format) and otio (the .otio / .fcpxml interchange, via the native oakotio crate). The database backend (PostgreSQL + SQLite, SeaORM) is a declared stub for a later proxy — not registered, todo!() bodies. Consumers never branch on backend.

Architectural decisions

URI dispatch, not file paths. Every entry point takes a URI: file:///…proj.ove / file:///…proj.otio / oakdb://…. Bare paths are normalized to file://. The core resolves scheme + backend can_handle arbitration (M10 §2.3).
Manual vtable backends (backend.rs StorageBackend trait = the M10 C vtable's Rust shape). The public C ABI vtable (oakstorage_backend_register) accepts foreign (C-side) backends — the database-swap interface proof — and in-crate backends implement the Rust trait directly.
The graph (de)serialization itself stays in oaknode — every backend calls the oaknode serializer (oaknode::serializer::load / save) through bridge::node (direct Rust calls, single-lib unification) to fetch/rebuild the in-memory graph; backends own framing: container bytes, schema, versioning (TOO_OLD/TOO_NEW/ UNKNOWN_VERSION), sessions. OAKSTORAGE_SAVE_COMPRESS is accepted but not implemented (the oaknode serializer emits plain XML only).
Database backend shares one logical schema across PostgreSQL and SQLite via SeaORM: a private current-thread tokio runtime drives the async API behind the synchronous C ABI; the entity set is minimal (projects table: id, name, payload blob, version, timestamps). The graph payload is the same serialized form the ove-xml backend uses — one serialization truth, two containers.
No callbacks/events (M10: synchronous commands only; the caller — oaktask/facade — owns progress reporting).
Errors follow the project -MMCCCC scheme, module 10 (-100001 …); the M10 positive info codes (TOO_OLD/TOO_NEW/…) are kept verbatim.
Interchange is lossy. The otio backend's export/import mapping preserves sequences/tracks/clips/gaps/transitions; effect chains, keyframes, project bins/settings and exact rational timebases are not carried (see the module docs in backends/otio.rs).

Layout

src/
  lib.rs          crate doc + module map
  error.rs        error/info codes (M10 §2.1, -MMCCCC module 10)
  handle.rs       shared CHandle re-export (boxes live in oaknode's handle.rs)
  uri.rs          URI parsing/classification
  session.rs      StorageProject session (open/take/uri)
  registry.rs     backend registry (register/unregister/arbitrate)
  backend.rs      StorageBackend trait + LoadResult
  backends/
    ove_xml.rs    built-in .ove XML backend (via bridge::node)
    otio.rs       built-in .otio/.fcpxml backend (via oakotio)
    database.rs   declared stub (later proxy)
  bridge/
    node.rs       oaknode calls (project + serializer + sequence builder)
  ffi.rs          export layer (M10 §2.2/§2.3 verbatim)
tests/            contract tests incl. the pluggability proof

Build / test

A workspace member (not a default member); build and test explicitly:

cargo test -p oakstorage