stardesign.storage Namespace Reference

Classes
class	LocalBackend
class	S3Backend

Functions
str	_now_iso ()
None	_atomic_write (Path path, Snapshot data)
Snapshot|None	_read_json (Path path)
	make_backend (UserData ud, str bucket_env, str prefix_env, str default_prefix)

Variables
	Snapshot = dict[str, Any]

Detailed Description

Version storage for designs: microversions + immutable releases.

Payload-agnostic: it stores and returns whatever JSON dict it is given, which is
why one module serves an engine design (``{"config": ...}``), a recovery config
and a P&ID (``{"nodes": ..., "edges": ...}``) alike. The *working copy*
(``current.json`` on the volume) is owned by the router
(:mod:`stardesign.documents`); here we only keep version history.

Two backends, chosen by :func:`make_backend` from the environment:

* **S3Backend** when the app's bucket variable is set. Microversions ride on S3
  object *versioning* of a per-document HEAD key
  (``<prefix>/<user>/<id>/current.json``): every snapshot is a plain
  ``put_object`` that S3 keeps as a new version, and a lifecycle rule prunes old
  ones. Releases are separate immutable keys under ``.../releases/<label>.json``.
  Credentials come from the standard ``AWS_*`` env vars.

  This is also why designs are *not* stored in a flat, ownerless tree: the
  microversion history of a design IS the S3 version history of one key, so
  re-keying a design to a new owner-less path would flatten it.

* **LocalBackend** otherwise (dev, and prod with no bucket set). Microversions
  and releases are files on disk under the ``USERDATA_DIR`` tree, so history
  works with no AWS.

Function Documentation

_atomic_write()

None stardesign.storage._atomic_write ( Path path, Snapshot data )

protected

Definition at line 49 of file storage.py.

Referenced by stardesign.storage.LocalBackend.create_release(), and stardesign.storage.LocalBackend.snapshot_micro().

_now_iso()

str stardesign.storage._now_iso ( )

protected

Definition at line 43 of file storage.py.

Referenced by stardesign.storage.LocalBackend.create_release(), stardesign.storage.S3Backend.create_release(), stardesign.storage.LocalBackend.snapshot_micro(), and stardesign.storage.S3Backend.snapshot_micro().

_read_json()

Snapshot | None stardesign.storage._read_json ( Path path )

protected

Definition at line 63 of file storage.py.

Referenced by stardesign.storage.LocalBackend.get_micro(), and stardesign.storage.LocalBackend.get_release().

make_backend()

stardesign.storage.make_backend	(	UserData	ud,
		str	bucket_env,
		str	prefix_env,
		str	default_prefix )

The version-history backend for one app, chosen from the environment.

Called once per app at import time, so a missing bucket means "local files"
for the life of the process rather than a per-request branch.

Definition at line 248 of file storage.py.

Variable Documentation

Snapshot

stardesign.storage.Snapshot = dict[str, Any]

Definition at line 40 of file storage.py.