nuspace 0.1.0__py3-none-any.whl

nuspace/__init__.py

@@ -0,0 +1,40 @@
+"""Nuspace: a space that runs applications over one shape tree, built on Nu.
+
+Rebuild in progress. The imperative driver layer was deleted wholesale
+because it was python wearing a Nu costume: Control atoms holding opaque
+callables, per-run state on host objects, and a python -> Nu -> arun ->
+python cycle instead of one tree.
+
+What nuspace is meant to be is one large Nu program. Storage shapes, the
+tpl registry and the wysiwyg template below survived because they are
+already that. Everything else gets written against the guides in
+``go/progress/tasks/task-144-nuspace-v1/reference/``.
+"""
+
+from nuspace.apps import App, run_apps
+from nuspace.core import (
+    TPL_PROGRAM,
+    TPL_TEXT,
+    Space,
+    Tpl,
+    mint_ordered_id,
+    resolve,
+)
+from nuspace.pages import Page, Section, page_tree
+
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "TPL_PROGRAM",
+    "TPL_TEXT",
+    "App",
+    "Page",
+    "Section",
+    "Space",
+    "Tpl",
+    "mint_ordered_id",
+    "page_tree",
+    "resolve",
+    "run_apps",
+]

nuspace/_root.py

@@ -0,0 +1,34 @@
+"""Which space root class a call addresses, resolved at call time.
+
+``core.shapes`` imports the per-submodule shapes to build ``Space``, so a
+submodule that named ``Space`` at import time would close the cycle. This is
+the one place the import is deferred instead.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from nuspace.core import Space
+
+
+__all__ = ["resolve_root"]
+
+
+def resolve_root(root: type[Space] | None) -> type[Space]:
+    """``root``, or ``Space`` when it is None.
+
+    ``Space.apps`` and ``DemoSpace.apps`` are different addresses, so an op
+    against a subclassed space has to be told which root it is working.
+
+    Args:
+        root: the space's root Shape class, or None for the stock ``Space``.
+    """
+    if root is not None:
+        return root
+    # Deferred on purpose: see the module docstring.
+    from nuspace.core.shapes import Space
+
+    return Space

nuspace/apps/__init__.py

@@ -0,0 +1,75 @@
+"""nuspace.apps -- every app in the space, running, as one Nu tree.
+
+Module layout:
+
+- :mod:`.shapes` -- store layout (``App``) and the host's own ``Runner``.
+- :mod:`.ops`    -- write + read primitives (``add_app`` / ``snippet_of`` / ...).
+  What a ui, a cli or an agent calls instead of writing ref chains.
+- :mod:`.runner` -- the driver: seed, reconcile, live loop, ``run_apps``.
+
+No ``interactions`` module: every op here is a plain ``-> Nu`` function over
+existing atoms, and nothing in this layer touches the host directly.
+"""
+
+from __future__ import annotations
+
+from .ops import (
+    add_app,
+    app_ids,
+    attached,
+    error_of,
+    exists,
+    is_running,
+    remove_app,
+    rename_app,
+    running,
+    set_policy,
+    set_snippet,
+    snippet_of,
+)
+from .runner import (
+    CHANGED_APP_INDEX,
+    DEFAULT_CHANNEL_PREFIX,
+    app_body,
+    apps_store,
+    apps_tree,
+    changed_app,
+    driver,
+    free_port,
+    reconcile,
+    run_apps,
+    supervisor,
+    worker_init,
+)
+from .shapes import DEFAULT_POLICY, App, Runner
+
+
+__all__ = [
+    "CHANGED_APP_INDEX",
+    "DEFAULT_CHANNEL_PREFIX",
+    "DEFAULT_POLICY",
+    "App",
+    "Runner",
+    "add_app",
+    "app_body",
+    "app_ids",
+    "apps_store",
+    "apps_tree",
+    "attached",
+    "changed_app",
+    "driver",
+    "error_of",
+    "exists",
+    "free_port",
+    "is_running",
+    "reconcile",
+    "remove_app",
+    "rename_app",
+    "run_apps",
+    "running",
+    "set_policy",
+    "set_snippet",
+    "snippet_of",
+    "supervisor",
+    "worker_init",
+]

nuspace/apps/ops.py

@@ -0,0 +1,280 @@
+"""Write + read primitives over the apps store.
+
+Every one returns a Nu tree and nothing else, so a ui, a cli or an agent
+composes them instead of hand-writing ref chains. ``root`` is the space's own
+root Shape class, resolved at call time by :func:`~nuspace._root.resolve_root`
+so this module never needs ``Space`` while it is being imported.
+
+Write:
+- :func:`init_apps`   -- the container, once, on a cold store.
+- :func:`add_app`     -- every field of a new app, in one tree.
+- :func:`remove_app`  -- drop the row. The runner kills the worker.
+- :func:`set_snippet` / :func:`rename_app` / :func:`set_policy` -- one field.
+- :func:`clear_error` -- forget what the runner last recorded.
+
+Read:
+- :func:`app_ids` / :func:`exists` / :func:`snippet_of` / :func:`error_of`
+  -- the store.
+- :func:`running` / :func:`is_running` / :func:`attached` -- the host's own
+  ``Runner``, which is mem and therefore only readable from inside the
+  process the runner is in.
+- whole rows, one dict per app: :func:`app_rows` / :func:`app_statuses`. What
+  a rail or a status bar is filled from.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import nu
+from nuspace._root import resolve_root
+from nuspace.core.ids import mint_ordered_id
+
+from .shapes import DEFAULT_POLICY, Runner
+
+
+if TYPE_CHECKING:
+    from nu.domains.shape import Shape
+
+
+__all__ = [
+    "add_app",
+    "app_ids",
+    "app_rows",
+    "app_statuses",
+    "attached",
+    "clear_error",
+    "error_of",
+    "exists",
+    "init_apps",
+    "is_running",
+    "remove_app",
+    "rename_app",
+    "running",
+    "set_policy",
+    "set_snippet",
+    "snippet_of",
+]
+
+
+#: The name ``Map`` binds the current element under, and the ref that reads it.
+_ITEM = "_na_item"
+_item = nu.AnyAttrRef(_ITEM)
+
+
+def _state_key(app_id: nu.StrArg, suffix: str) -> nu.Nu:
+    """``apps.<app_id><suffix>`` as a term, for either a python str or a term."""
+    return nu.Str("apps.") + app_id + nu.Str(suffix)
+
+
+# --- write: the space ------------------------------------------------------
+
+
+def init_apps(*, root: type[Shape] | None = None) -> nu.Nu:
+    """Create the apps container if the store has none. Idempotent.
+
+    A subscription over a missing container resolves to INVALID and silently
+    never fires, so anything that means to watch ``apps`` boots through here
+    first. ``Dict.create()``, not ``{}``: a literal is captured once at Form
+    construction and shared across every evaluation of the term.
+    """
+    return resolve_root(root).apps.init(nu.Dict.create())
+
+
+# --- write -----------------------------------------------------------------
+
+
+def add_app(
+    source: nu.StrArg,
+    *,
+    app_id: nu.StrArg | None = None,
+    name: nu.StrArg | None = None,
+    policy: nu.StrArg = DEFAULT_POLICY,
+    root: type[Shape] | None = None,
+) -> nu.Nu:
+    """Write a whole app: id, name, policy and source, in one tree.
+
+    Args:
+        source: the snippet, a ``nu.prog`` module with an ``out`` entry point.
+        app_id: the app's key. Minted in creation order when absent, in which
+            case the caller never learns it -- pass ``mint_ordered_id("a")``
+            yourself if you mean to address the app afterwards.
+        name: what to call it. Defaults to the id.
+        policy: when it runs. Nothing reads it yet.
+        root: the space's root Shape class.
+    """
+    # Minted while the tree is built, not while it runs, so re-running one tree
+    # rewrites one app rather than adding another.
+    app_id = mint_ordered_id("a") if app_id is None else app_id
+    app = resolve_root(root).apps[app_id]
+    # Snippet last: every field write wakes its own reconcile, so this order
+    # leaves the pass that actually launches the app holding the final source.
+    return (
+        app.name.set(app_id if name is None else name)
+        >> app.policy.set(policy)
+        >> app.snippet.set(source)
+    )
+
+
+def remove_app(app_id: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """Drop an app from the store. A no-op when it is not there."""
+    apps = resolve_root(root).apps
+    # Guarded rather than bare: del_item on a missing key raises, and removing
+    # something already gone is exactly what a retried ui click does.
+    return nu.IfDo(apps.contains(app_id), apps.del_item(app_id))
+
+
+def set_snippet(app_id: nu.StrArg, source: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """Replace an app's source. The runner restarts that app and no other."""
+    return resolve_root(root).apps[app_id].snippet.set(source)
+
+
+def rename_app(app_id: nu.StrArg, name: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """Replace an app's display name. The id does not move."""
+    return resolve_root(root).apps[app_id].name.set(name)
+
+
+def set_policy(app_id: nu.StrArg, policy: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """Replace an app's policy string."""
+    return resolve_root(root).apps[app_id].policy.set(policy)
+
+
+def clear_error(app_id: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """Forget the construction error recorded for this app. A no-op when clean.
+
+    Guarded rather than bare: ``del_item`` on a missing key raises, and an app
+    that never failed has no key.
+    """
+    state = resolve_root(root).state
+    key = _state_key(app_id, ".error")
+    return nu.IfDo(state.contains(key), state.del_item(key))
+
+
+# --- read ------------------------------------------------------------------
+
+
+def app_ids(*, root: type[Shape] | None = None) -> nu.Nu:
+    """Every app id in the space, as a list."""
+    # nu.list, not the bare keys view: the view is lazy and dies with its
+    # Snapshot, so an undrained one reads as StorageClosedError later.
+    return nu.list(resolve_root(root).apps.keys())
+
+
+def exists(app_id: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """Whether the store has an app under this id."""
+    return resolve_root(root).apps.contains(app_id)
+
+
+def snippet_of(app_id: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """An app's source, verbatim. EMPTY when there is no such app."""
+    return resolve_root(root).apps[app_id].snippet
+
+
+def error_of(app_id: nu.StrArg, *, root: type[Shape] | None = None) -> nu.Nu:
+    """The construction error the runner recorded for this app, or ``""``.
+
+    Written by ``app_body`` when a snippet does not construct, since a
+    dispatched body has no waiter to raise into.
+    """
+    return resolve_root(root).state.get_item(_state_key(app_id, ".error"), nu.Str(""))
+
+
+def running() -> nu.Nu:
+    """Which apps have a worker, and its pool id, as a dict.
+
+    ``Runner.workers`` is mem in the host process, so this only answers inside
+    the runner's own tree.
+    """
+    return nu.dict(Runner.workers.items())
+
+
+def is_running(app_id: nu.StrArg) -> nu.Nu:
+    """Whether this app has a worker on record right now."""
+    return Runner.workers.contains(app_id)
+
+
+def attached() -> nu.Nu:
+    """Whether a runner is supervising apps in this very process. A live read.
+
+    Total, and true only where the bookkeeping really is: the ``FabricExists``
+    half answers False rather than raising where no ``dict`` is bound at all,
+    and ``Runner.attached`` is mem, so a runner in another process cannot make
+    this say yes.
+    """
+    return nu.And(nu.FabricRef(dict).exists(), nu.NotEmpty(Runner.attached))
+
+
+# --- read: whole rows ------------------------------------------------------
+#
+# Both answer with a list of dicts rather than a scalar, so one read fills a
+# rail or a status bar. They exist because a caller that wants every app would
+# otherwise read the ids and then loop in its own language, which puts a python
+# (or a javascript) for-loop back in the middle of what is meant to be one tree.
+
+
+def app_rows(*, root: type[Shape] | None = None) -> nu.Nu:
+    """Every app as ``{id, name, source, policy}``, one dict per app.
+
+    Keys sort by mint time, so this is creation order with no order slot.
+    """
+    apps = resolve_root(root).apps
+    app = apps[_item]
+    return nu.Collect(
+        nu.Map(
+            # nu.list, not the bare keys view, for the reason app_ids gives.
+            nu.list(apps.keys()),
+            nu.Dict.of(id=_item, name=app.name, source=app.snippet, policy=app.policy),
+            key=_ITEM,
+        )
+    )
+
+
+def _live(supervised: nu.BoolArg) -> nu.Nu | None:
+    """Whether the app ``Map`` is on has a worker, or None when nobody asked.
+
+    ``supervised`` is ``False`` for a tree that must not touch mem at all, and
+    a term for one that wants the answer read rather than assumed.
+    """
+    if supervised is False:
+        return None
+    running_now = is_running(nu.StrAttrRef(_ITEM))
+    if supervised is True:
+        return running_now
+    return nu.And(supervised, running_now)
+
+
+def app_statuses(*, supervised: nu.BoolArg = False, root: type[Shape] | None = None) -> nu.Nu:
+    """Every app as ``{section_id, state, error, started_at}``, in the same order.
+
+    ``section_id`` rather than ``app_id`` because this is the supervisor's
+    contract, not the Apps surface's: an app and a section are the same
+    substance and share one status shape. An app whose namespace holds an
+    ``error`` key reads ``failed``.
+
+    Args:
+        supervised: whether ``Runner.workers`` is readable here, which it only
+            is inside the runner's own tree. ``False`` never claims an app is
+            running and never touches mem; ``True`` reads it outright; a term
+            (see :func:`attached`) reads whether to read it, which is what a
+            web driver that may or may not share a process with a runner wants.
+        root: the space's root Shape class.
+    """
+    root = resolve_root(root)
+    # Same binding Map makes, read as a Str so `+` concatenates rather than
+    # collapsing to INVALID the way it would on an untyped AnyAttrRef.
+    key = _state_key(nu.StrAttrRef(_ITEM), ".error")
+    idle = nu.Str("idle")
+    live = _live(supervised)
+    quiet = idle if live is None else nu.If(live, nu.Str("running"), idle)
+    return nu.Collect(
+        nu.Map(
+            app_ids(root=root),
+            nu.Dict.of(
+                section_id=_item,
+                state=nu.If(root.state.contains(key), nu.Str("failed"), quiet),
+                error=nu.ToStr(root.state.get_item(key, nu.Str(""))),
+                started_at=nu.Int(0),
+            ),
+            key=_ITEM,
+        )
+    )

nuspace/apps/runner.py

@@ -0,0 +1,250 @@
+"""The apps driver: every app in the space, running, as one Nu tree.
+
+One ``arun`` owns it: seed from the store, then react to it forever, with a
+single reconcile path covering add, edit and delete. A snippet owns its own
+atomicity, and without ``redis_url`` a worker can read and write the store
+but cannot react to another process's writes.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import nu
+import nu.kv
+import nu.mp_pool
+import nu.prog
+from nuspace._root import resolve_root
+from nuspace.core.host import DEFAULT_CHANNEL_PREFIX, free_port, host, worker_init
+
+from .shapes import Runner
+
+
+if TYPE_CHECKING:
+    from nu.domains.shape import Shape
+
+
+__all__ = [
+    "CHANGED_APP_INDEX",
+    "DEFAULT_CHANNEL_PREFIX",
+    "app_body",
+    "apps_store",
+    "apps_tree",
+    "changed_app",
+    "driver",
+    "free_port",
+    "reconcile",
+    "run_apps",
+    "supervisor",
+    "worker_init",
+]
+
+
+#: Position of the app id in a key from ``Space.apps.on_change()``. The
+#: subscription is depth-unbounded, so a key is either ``('/', 'apps', id)`` or
+#: ``('/', 'apps', id, field)``; index 2 reaches the id in both. Measured, and
+#: pinned by ``tests/nuspace/apps/test_changed_key.py``.
+CHANGED_APP_INDEX = 2
+
+
+#: The app a reconcile pass is about, carried into the worker by ``carry=True``.
+_APP = nu.StrAttrRef("app")
+
+#: The pool worker a reconcile pass just launched.
+_WORKER = nu.IntAttrRef("w")
+
+#: The key that woke the live loop, and the app id inside it.
+_KEY = nu.TupleAttrRef("k")
+changed_app = _KEY[CHANGED_APP_INDEX]
+
+
+def app_body(*, root: type[Shape] | None = None) -> nu.Nu:
+    """One app running, as the single term every ``Dispatch`` ships.
+
+    One per space, not one per app: a ``Dispatch`` body is payload, so it is
+    fixed at construction and the app arrives as the carried attr ``app``. The
+    ``auto_flow_atomic`` covers the runner's own ``LoadNu`` read and stops
+    there, since the pass does not descend through ``Eval``.
+    """
+    root = resolve_root(root)
+    # Construction failures are written to the app's namespace, not raised: a
+    # dispatched body has no waiter, so an uncaught error vanishes silently.
+    load = root.apps[_APP].snippet.load(scope={"path": nu.Str("apps.") + _APP})
+    report = nu.kv.auto_flow_atomic(
+        root.state.set_item(
+            nu.Str("apps.") + _APP + nu.Str(".error"), nu.ToStr(nu.AttrRef("error"))
+        ),
+        scope=root,
+    )
+    return nu.TryCatch(
+        nu.prog.Eval(nu.kv.auto_flow_atomic(load, scope=root)),
+        catch=report,
+        errors=nu.prog.ConstructionError,
+    )
+
+
+def reconcile(*, root: type[Shape] | None = None) -> nu.Nu:
+    """Make the world agree with the store, for the one app bound at ``app``.
+
+    One path for add, edit and delete: whatever is running for this app stops,
+    and if the store still has the app it starts again. ``Launch``, ``Dispatch``
+    and ``Kill`` all return promptly, so the seed can run this sequentially
+    without the first app blocking the rest.
+    """
+    root = resolve_root(root)
+    pool = nu.mp_pool.PoolRef()
+    stop = nu.IfDo(
+        Runner.workers.contains(_APP),
+        pool.kill(Runner.workers[_APP]) >> Runner.workers.del_item(_APP),
+    )
+    start = nu.IfDo(
+        # An app that has been deleted reaches here too -- that is the delete
+        # path, and this is what stops it coming back.
+        root.apps.contains(_APP),
+        # The worker id is read twice, recorded and then dispatched to, so it
+        # is bound once and scoped to the two reads that want it.
+        nu.Let(
+            "w",
+            pool.launch(),
+            body=Runner.workers.set_item(_APP, _WORKER)
+            >> pool.dispatch(app_body(root=root), _WORKER, carry=True),
+        ),
+    )
+    return stop >> start
+
+
+def driver(*, root: type[Shape] | None = None) -> tuple[nu.Nu, nu.Nu]:
+    """The seed pass and the live loop, as two terms.
+
+    Returned separately because they compose differently: the seed must finish
+    before anything else starts, and the live loop never finishes at all.
+    """
+    root = resolve_root(root)
+    body = reconcile(root=root)
+    # Both containers must exist before anything reads them: a subscription
+    # over a missing container resolves to INVALID and silently never fires.
+    # Dict.create(), not {} -- a literal dict is captured once at Form
+    # construction and shared across every evaluation of the term.
+    #
+    # `attached` is the marker a web driver in this same process reads to say
+    # whether anything is supervising at all. It is written here rather than
+    # assumed by whoever assembled the tree, so the browser is told what is
+    # true rather than what the build script believed.
+    boot = (
+        root.apps.init(nu.Dict.create())
+        >> Runner.workers.init(nu.Dict.create())
+        >> Runner.attached.set(nu.Bool(True))
+    )
+    # nu.list is load-bearing: the keys view is lazy and auto_flow_atomic
+    # brackets the items slot separately, so an undrained view outlives its
+    # Snapshot and dies with StorageClosedError.
+    seed = boot >> nu.ForEachDo(nu.list(root.apps.keys()), body, item="app")
+    # The bare key ('/', 'apps') also fires, naming no app. It must be skipped
+    # explicitly: indexing past the end raises IndexError inside the react
+    # loop, killing it and leaving the runner silently deaf.
+    live = nu.ReactForever(
+        root.apps.on_change(),
+        nu.IfDo(
+            nu.Len(_KEY) > nu.Int(CHANGED_APP_INDEX),
+            # Same binding the seed pass makes with ForEachDo(item="app"), and
+            # scoped the same way, so no reaction leaves one behind.
+            nu.Let("app", changed_app, body=body),
+        ),
+        changed_key="k",
+    )
+    return seed, live
+
+
+def supervisor(
+    *,
+    root: type[Shape] | None = None,
+    alongside: nu.Nu | None = None,
+    duration: float | None = None,
+) -> nu.Nu:
+    """Every app in the space, supervised, as one term for whoever mounts it.
+
+    No ``With`` head: the store, the pool and the ``dict`` behind
+    ``Runner.workers`` come from the context this is run in, which is what
+    lets a web server and this share one process and one store.
+
+    Args:
+        root: the space's root Shape class.
+        alongside: a tree to run beside the live loop, for demos and tests.
+        duration: stop after this many seconds. None runs forever.
+    """
+    root = resolve_root(root)
+    seed, live = driver(root=root)
+    flow = live if alongside is None else (live | alongside)
+    if duration is not None:
+        flow = nu.Race(flow, nu.DelayedDo(nu.Float(duration), nu.Noop()))
+    return nu.kv.auto_flow_atomic(seed >> flow, scope=root)
+
+
+def apps_store(
+    path: str,
+    *,
+    redis_url: str | None = None,
+    channel_prefix: str = DEFAULT_CHANNEL_PREFIX,
+) -> nu.Nu:
+    """The navigator bracket for a space on disk, with or without redis."""
+    if redis_url is None:
+        return nu.kv.rocksdb_navigator(path)
+    return nu.kv.rocksdb_navigator_redis(path, redis_url=redis_url, channel_prefix=channel_prefix)
+
+
+def apps_tree(
+    *,
+    path: str,
+    address: str,
+    root: type[Shape] | None = None,
+    redis_url: str | None = None,
+    channel_prefix: str = DEFAULT_CHANNEL_PREFIX,
+    alongside: nu.Nu | None = None,
+    duration: float | None = None,
+) -> nu.Nu:
+    """The whole runner: one tree, for one ``arun``.
+
+    Args:
+        path: the store directory. This tree takes its write lock, which is
+            why workers reach it through a proxy rather than opening it.
+        address: where the Navigator is served, ``host:port``.
+        root: the space's root Shape class. Defaults to ``Space``.
+        redis_url: Redis carrying change notifications, or None.
+        channel_prefix: namespaces the Redis channels.
+        alongside: a tree to run beside the live loop, for demos and tests.
+        duration: stop after this many seconds. None runs forever.
+
+    Returns:
+        The tree. Brackets tear down LIFO when it ends, reaping every worker.
+    """
+    return host(
+        supervisor(root=root, alongside=alongside, duration=duration),
+        store=apps_store(path, redis_url=redis_url, channel_prefix=channel_prefix),
+        address=address,
+        redis_url=redis_url,
+        channel_prefix=channel_prefix,
+    )
+
+
+async def run_apps(
+    path: str,
+    *,
+    address: str | None = None,
+    root: type[Shape] | None = None,
+    redis_url: str | None = None,
+    channel_prefix: str = DEFAULT_CHANNEL_PREFIX,
+    alongside: nu.Nu | None = None,
+    duration: float | None = None,
+    max_parallel: int = 64,
+) -> None:
+    """Assemble the tree and run it. Deployment glue, nothing else."""
+    tree = apps_tree(
+        path=path,
+        address=address or f"127.0.0.1:{free_port()}",
+        root=root,
+        redis_url=redis_url,
+        channel_prefix=channel_prefix,
+        alongside=alongside,
+        duration=duration,
+    )
+    await nu.arun(tree, nu.Context(), max_parallel=max_parallel)