seamless-workflow 0.2.0__py3-none-any.whl

seamless_workflow/__init__.py

@@ -0,0 +1,40 @@
+"""Reactive workflow layer for Seamless."""
+
+__version__ = "0.1.0"
+from .context import Context
+from seamless import Cell
+from seamless_transformer import Transformer
+from .endpoints import BoundEndpoint
+from . import shareserver
+from .errors import (
+    AuthorityError,
+    DependencyError,
+    PathError,
+    ReadOnlyEndpointError,
+    StaleWorkflowHandleError,
+    ValueUnavailableError,
+    ClosedContextError,
+    ConcurrentUpdateError,
+    ControllerFailedError,
+    ReentrantContextError,
+    WorkflowExecutionError,
+)
+
+__all__ = [
+    "AuthorityError",
+    "BoundEndpoint",
+    "Context",
+    "Cell",
+    "Transformer",
+    "DependencyError",
+    "PathError",
+    "ReadOnlyEndpointError",
+    "StaleWorkflowHandleError",
+    "ValueUnavailableError",
+    "ClosedContextError",
+    "ConcurrentUpdateError",
+    "ControllerFailedError",
+    "ReentrantContextError",
+    "WorkflowExecutionError",
+    "shareserver",
+]

seamless_workflow/adapters.py

@@ -0,0 +1,50 @@
+"""Narrow substrate adapters used by the workflow layer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from seamless import Buffer, Checksum
+
+
+def checksum_for_value(
+    value: Any, celltype: str = "mixed", *, checksum_is_value: bool = False
+) -> Checksum:
+    """Serialize a Python value and return its checksum.
+
+    An explicit Checksum is already serialized state, and is returned as it is.
+    The exception is a written value (``checksum_is_value``) of celltype
+    ``checksum``: there a Checksum is the value itself.
+    """
+
+    # Ordinary 64-character strings are never reinterpreted as checksums.
+    if isinstance(value, Checksum) and not (checksum_is_value and celltype == "checksum"):
+        return value
+    buffer = Buffer(value, celltype)
+    checksum = buffer.get_checksum()
+    buffer.tempref()
+    return checksum
+
+
+def buffer_for_checksum(checksum: Checksum | str | bytes | None):
+    if checksum is None:
+        return None
+    return Checksum(checksum).resolve()
+
+
+def value_for_checksum(checksum: Checksum | str | bytes | None, celltype: str = "mixed"):
+    if checksum is None:
+        return None
+    return Checksum(checksum).resolve(celltype)
+
+
+def normalize_checksum(checksum: Checksum | str | bytes) -> Checksum:
+    return Checksum(checksum)
+
+
+__all__ = [
+    "checksum_for_value",
+    "buffer_for_checksum",
+    "value_for_checksum",
+    "normalize_checksum",
+]

seamless_workflow/assignment.py

@@ -0,0 +1,8 @@
+"""Assignment helper namespace.
+
+The implementation currently keeps assignment methods on :mod:`context` because they
+need direct access to graph mutation internals. This module is intentionally present
+as the public scaffold extension point named by the implementation handoff.
+"""
+
+__all__: list[str] = []

seamless_workflow/attachments/__init__.py

@@ -0,0 +1,3 @@
+"""Context attachments and file mounts."""
+from .spec import AttachmentSpec
+from .session import MountError, ConflictError, SyncReport

seamless_workflow/attachments/api.py

@@ -0,0 +1,217 @@
+"""Caller-side mount preparation and public handles."""
+import asyncio
+import weakref
+from concurrent.futures import Future
+from uuid import uuid4
+from .spec import AttachmentSpec
+from .fs.service import get_service
+from ..errors import ClosedContextError, ControllerFailedError
+
+
+def make_sink(controller):
+    reference = weakref.ref(controller)
+    def sink(operation, payload):
+        def fail(error):
+            if hasattr(payload, 'release'):
+                payload.release()
+            reply = Future()
+            reply.set_exception(error)
+            return reply
+        owner = reference()
+        if owner is None:
+            return fail(ClosedContextError("Context is closed"))
+        try:
+            reply = owner.enqueue(operation, (payload,), klass=3 if operation == '_mount_observed' else 5,
+                                  internal=operation != '_mount_observed')
+        except (ClosedContextError, ControllerFailedError) as exc:
+            return fail(exc)
+        except BaseException as exc:
+            return fail(exc)
+        else:
+            if hasattr(payload, 'release'):
+                # Also covers accepted messages discarded by stop or poison.
+                reply.add_done_callback(lambda future: payload.release())
+            return reply
+    return sink
+
+
+class MountHandle:
+    def __init__(self, backend):
+        self.backend = backend
+
+    def _context(self):
+        b = self.backend
+        b.context._check_public_caller()
+        if getattr(b, "local_path", ()) or getattr(b, "readonly", False):
+            raise AttributeError('Only whole Context cell nodes can be mounted')
+        from ..errors import NodeError, StaleWorkflowHandleError
+
+        try:
+            b._node()
+        except StaleWorkflowHandleError as exc:
+            raise NodeError('Mounts require an existing whole cell node') from exc
+        return b.context, b.node_path
+
+    def __call__(self, path, mode='rw', authority='file', *, persistent=True):
+        ctx, node_path = self._context()
+        spec = AttachmentSpec(path, mode, authority, persistent)
+        celltype = ctx._controller.call('_mount_validate', node_path, spec, klass=4)
+        service = get_service()
+        registration = service.reserve(spec, celltype, uuid4().hex, make_sink(ctx._controller))
+        try:
+            observation = service.initial_read(registration).result()
+            try:
+                initial = ctx._controller.call('_mount_attach', node_path, spec, registration, observation, klass=2)
+            finally: observation.release()
+            initial.result()
+        except Exception:
+            service.unregister(registration).result()
+            raise
+
+    def unmount(self):
+        ctx, path = self._context()
+        future = ctx._controller.call('_mount_detach', path, klass=2)
+        if future is not None: future.result(get_service().delivery_timeout)
+
+    @property
+    def spec(self):
+        ctx, path = self._context()
+        return ctx._node_snapshot(path).mount
+
+    @property
+    def status(self):
+        ctx, path = self._context()
+        return ctx._controller.call('_mount_status', path, klass=4)
+
+    @property
+    def error(self):
+        status = self.status
+        return None if status is None else status['error']
+
+    def clear_error(self):
+        ctx, path = self._context()
+        ctx._controller.call('_mount_clear_error', path, klass=2)
+
+
+class ContextMounts:
+    def __init__(self, context): self.context = context
+
+    def sync(self, timeout=None):
+        ctx = self.context
+        ctx._check_public_caller()
+        future = ctx._controller.call('_mount_sync', klass=1)
+        try: return future.result(timeout)
+        finally:
+            if ctx._controller.accepting: ctx._controller.call('_withdraw_wait', future, klass=1)
+
+    async def synchronization(self, timeout=None):
+        ctx = self.context
+        ctx._check_public_caller()
+        installed = ctx._controller.submit('_mount_sync', klass=1)
+        try: future = await asyncio.shield(asyncio.wrap_future(installed))
+        except asyncio.CancelledError:
+            def withdraw(reply):
+                if not reply.cancelled() and reply.exception() is None:
+                    ctx._controller.notify('_withdraw_wait', (reply.result(),), klass=1)
+            installed.add_done_callback(withdraw)
+            raise
+        try:
+            return await asyncio.wait_for(asyncio.shield(asyncio.wrap_future(future)), timeout)
+        finally:
+            if ctx._controller.accepting:
+                await asyncio.wrap_future(ctx._controller.submit('_withdraw_wait', (future,), klass=1))
+
+    @property
+    def errors(self):
+        report = self.context._controller.call('_mount_report', klass=4)
+        return {p: s['error'] or s['sense_error'] for p, s in report.items() if s['error'] or s['sense_error']}
+
+
+def load_graph(ctx, data, *, mounts=True, shares=True):
+    context_shares = ctx.shares
+    with context_shares._lock:
+        return _load_graph(
+            ctx, data, mounts=mounts, shares=shares,
+            context_shares=context_shares,
+        )
+
+
+def _load_graph(ctx, data, *, mounts=True, shares=True, context_shares):
+    """Load a graph, optionally restoring its file mounts, HTTP shares and downloads."""
+    import copy
+    from .spec import validate_celltype
+    from ..serialization import prepare_graph
+    graph = prepare_graph(copy.deepcopy(data))
+    old = ctx._controller.call('_mount_registrations', klass=4)
+    old_shares = tuple(
+        registration for registration in old
+        if getattr(getattr(registration, 'spec', None), 'driver', None) == 'share'
+    )
+    old_downloads = tuple(context_shares._downloads.values())
+    download_specs = graph.downloads if shares else {}
+    graph.downloads = dict(download_specs)
+    prepared, reservations = [], []
+    service = get_service() if mounts and any(n.mount for n in graph.nodes.values()) else None
+    share_prepared = []
+    download_registrations = []
+    share_driver = (
+        context_shares._driver
+        if shares and (download_specs or any('share' in n.attachments for n in graph.nodes.values()))
+        else None
+    )
+    try:
+        reads = []
+        for path, node in graph.nodes.items():
+            spec, node.mount = node.mount, None
+            share_spec = node.attachments.pop('share', None)
+            if spec is not None and mounts:
+                celltype = node.cell_config.celltype
+                validate_celltype(celltype, spec.mode)
+                reg = service.reserve(spec, celltype, uuid4().hex, make_sink(ctx._controller), replaces=old)
+                reservations.append(reg)
+                reads.append(('mount', path, spec, reg, service.initial_read(reg)))
+            if share_spec is not None and shares:
+                celltype = node.cell_config.celltype
+                reg = share_driver.reserve(
+                    share_spec, celltype, uuid4().hex, make_sink(ctx._controller),
+                    replaces=old_shares + old_downloads, staged=True, node_path=path,
+                )
+                reservations.append(reg)
+                reads.append(('share', path, share_spec, reg, share_driver.initial_read(reg)))
+        for download_spec in download_specs.values():
+            reg = share_driver.reserve_download(
+                download_spec, context_shares._download_provider(download_spec),
+                replaces=old_shares + old_downloads, staged=True,
+            )
+            reservations.append(reg)
+            download_registrations.append(reg)
+        if share_driver is not None:
+            share_driver.start()
+        for kind, path, spec, reg, future in reads:
+            prepared_item = (path, spec, reg, future.result())
+            (prepared if kind == 'mount' else share_prepared).append(prepared_item)
+        initial = ctx._controller.call(
+            'set_graph', graph, mount_prepared=tuple(prepared),
+            share_prepared=tuple(share_prepared),
+            download_registrations=tuple(download_registrations), klass=2,
+        )
+        for future in initial: future.result()
+        for reg in download_registrations:
+            share_driver.activate(reg).result(share_driver.delivery_timeout)
+    except BaseException:
+        for reg in reversed(reservations):
+            try:
+                future = reg.service.unregister(reg)
+                if future is not None:
+                    future.result(getattr(reg.service, 'delivery_timeout', 60))
+            except BaseException:
+                pass
+        raise
+    finally:
+        for _, _, _, observation in (*prepared, *share_prepared): observation.release()
+    # The old graph's downloads go with it, except those whose key a new
+    # share or download took over (already removed by the commit).
+    for reg in old_downloads:
+        if not reg.closed:
+            context_shares._driver.unregister(reg).result(context_shares._driver.delivery_timeout)
+    context_shares._downloads = {reg.spec.path: reg for reg in download_registrations}

seamless_workflow/attachments/fs/__init__.py

@@ -0,0 +1 @@
+"""Process-global filesystem transport."""

seamless_workflow/attachments/fs/native.py

@@ -0,0 +1,63 @@
+"""Optional Linux notifications. Polling remains the correctness fallback.
+
+Only directory watches are installed, so editor-style target replacement does
+not invalidate a watch. This source only marks registrations dirty; the normal
+transport still performs stable reads and owns watch sequences.
+"""
+import os
+import sys
+import struct
+
+
+class NativeNotifications:
+    def __init__(self):
+        self.fd = -1
+        self.watches = {}
+        if not sys.platform.startswith('linux'): return
+        try:
+            import ctypes
+            self.libc = ctypes.CDLL(None, use_errno=True)
+            self.libc.inotify_init1.argtypes = [ctypes.c_int]
+            self.libc.inotify_init1.restype = ctypes.c_int
+            self.libc.inotify_add_watch.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_uint32]
+            self.libc.inotify_add_watch.restype = ctypes.c_int
+            self.libc.inotify_rm_watch.argtypes = [ctypes.c_int, ctypes.c_int]
+            self.libc.inotify_rm_watch.restype = ctypes.c_int
+            self.fd = self.libc.inotify_init1(os.O_NONBLOCK | os.O_CLOEXEC)
+        except (AttributeError, OSError): pass
+
+    def poll(self, registrations):
+        if self.fd < 0: return set()
+        parents = {os.path.dirname(r.path) for r in registrations if r.active and not r.closed}
+        for path in set(self.watches) - parents:
+            self.libc.inotify_rm_watch(self.fd, self.watches.pop(path))
+        for path in parents - set(self.watches):
+            # MODIFY, ATTRIB, CLOSE_WRITE, MOVED_FROM/TO, CREATE, DELETE,
+            # DELETE_SELF and MOVE_SELF. Failed watches fall back to polling.
+            wd = self.libc.inotify_add_watch(self.fd, os.fsencode(path), 0x00000FCE)
+            if wd >= 0: self.watches[path] = wd
+        reverse = {wd: path for path, wd in self.watches.items()}
+        changed = set()
+        while True:
+            try: data = os.read(self.fd, 65536)
+            except BlockingIOError: break
+            except OSError: break
+            if not data: break
+            offset = 0
+            while offset + 16 <= len(data):
+                wd, mask, cookie, length = struct.unpack_from('iIII', data, offset)
+                name = os.fsdecode(data[offset+16:offset+16+length].split(b'\0', 1)[0])
+                offset += 16 + length
+                if mask & 0x00004000:  # queue overflow: request every path
+                    return {r.path for r in registrations}
+                parent = reverse.get(wd)
+                if parent is None: continue
+                if mask & 0x00008000:
+                    self.watches.pop(parent, None)
+                changed.add(os.path.join(parent, name) if name else parent)
+        return changed
+
+    def close(self):
+        if self.fd >= 0:
+            os.close(self.fd)
+            self.fd = -1