odysseys-py 0.0.1__py3-none-any.whl

odyssey/build_ledger.py

@@ -0,0 +1,64 @@
+class Build_ledger:
+    def __init__(self, get_conn, key, steps, delegates):
+        self.get_conn = get_conn
+        self.key = key
+        self.steps = steps
+        self.delegates = delegates or {}
+
+    def run(self):
+            
+        if not self.steps:
+            raise ValueError("build_ledger requires at least one step")
+
+        if len(self.steps) != len(set(self.steps)):
+            raise ValueError("steps must be unique")
+
+        unknown = set(self.delegates) - set(self.steps)
+        if unknown:
+            raise ValueError(f"delegates references steps not present in `steps`: {sorted(unknown)}")
+        
+        conn = self.get_conn()
+        ledger_rows = []
+        delivery_rows = []
+
+        try:
+            for target in self.steps:
+
+                if target in self.delegates:
+                    destination = self.delegates.get(target)
+                    delivery_rows.append((self.key, target, destination))
+                    ledger_rows.append((self.key, target, "delegated"))
+                else:
+                    ledger_rows.append((self.key, target, "local"))
+
+            with conn.cursor() as cur:
+                cur.executemany("""
+                INSERT INTO odyssey_ledger(
+                key,
+                target,
+                mode
+                )
+                VALUES(%s,%s,%s)
+                """, ledger_rows, )
+
+                cur.executemany("""
+                INSERT INTO odyssey_deliveries(
+                key,
+                target,
+                emit_to
+                )
+                VALUES(%s, %s, %s)
+                """, delivery_rows, )
+
+            conn.commit()
+            return {
+                "steps": len(ledger_rows),
+                "delegated": len(delivery_rows)
+            }
+
+        except Exception as e:
+            conn.rollback()
+            raise RuntimeError("Failed to build ledger") from e
+
+        finally:
+            conn.close()

odyssey/core.py

@@ -0,0 +1,171 @@
+import json
+from .utils import get_owner_id, row_to_dict
+from .results import AcquireResult, OperationResult, InspectResult
+
+def acquire(conn, key, *, owner_id=None, ttl_ms=10000):
+
+    owner_id = owner_id or get_owner_id()
+    ttl_ms = ttl_ms if ttl_ms and ttl_ms > 0 else 10000
+
+    row = None 
+
+    with conn.cursor() as cur:
+        cur.execute("""
+        INSERT INTO odyssey_journeys (
+            key,
+            owner_id,
+            expires_at,
+            updated_at,
+            fencing_token
+        )
+        VALUES (
+            %s,
+            %s,
+            NOW() + (%s * INTERVAL '1 millisecond'),
+            NOW(),
+            nextval('odyssey_token_seq')
+        )
+        ON CONFLICT (key)
+        DO UPDATE
+        SET
+            owner_id = EXCLUDED.owner_id,
+            expires_at = EXCLUDED.expires_at,
+            updated_at = NOW(),
+            fencing_token = nextval('odyssey_token_seq')
+        WHERE odyssey_journeys.expires_at < NOW() AND odyssey_journeys.status = 'claimed'
+        RETURNING owner_id, expires_at, fencing_token, status, expires_at > NOW() AS journey_alive;
+        """, (key, owner_id, ttl_ms))
+
+        result = cur.fetchone()
+
+        if result is not None:
+            row = row_to_dict(cur, result)
+
+    conn.commit()
+
+    if row is not None and row["fencing_token"] is None:
+        raise Exception("Invariant violation: fencing_token is None")
+
+    if row is not None:
+        return AcquireResult(
+            acquired=True,
+            owner_id=row["owner_id"],
+            expires_at=row["expires_at"],
+            journey_alive=row["journey_alive"],
+            fencing_token=row["fencing_token"],
+            status=row["status"]
+        )
+    
+    with conn.cursor() as cur:
+        cur.execute("""
+        SELECT owner_id, expires_at, fencing_token, status, expires_at > NOW() AS journey_alive
+        FROM odyssey_journeys
+        WHERE key = %s
+        """, (key,))
+
+        result = cur.fetchone()
+
+        if result is not None:
+            row = row_to_dict(cur, result)
+
+    if row is not None:
+        return AcquireResult(acquired=False,
+            owner_id=row["owner_id"],
+            expires_at=row["expires_at"],
+            journey_alive=row["journey_alive"],
+            fencing_token=row["fencing_token"],
+            status=row["status"])
+
+def start_execution(conn, key, *, fencing_token):
+
+    row = None
+    
+    with conn.cursor() as cur:
+        cur.execute("""
+        UPDATE odyssey_journeys
+        SET status = 'executing',
+            updated_at = NOW()
+        WHERE key = %s
+          AND fencing_token = %s
+          AND status = 'claimed'
+        RETURNING status;
+        """, (key, fencing_token))
+
+        result = cur.fetchone()
+        success = result is not None
+        if result is not None:
+            row = row_to_dict(cur, result)
+    
+    conn.commit()
+    if row is None:
+        return OperationResult(success)
+
+    return OperationResult(success, status=row["status"])
+
+def complete(conn, key, *, fencing_token, execution_result=None):
+
+    serialized_result = (
+        json.dumps(execution_result)
+        if execution_result is not None
+        else None
+    )
+
+    with conn.cursor() as cur:
+        cur.execute("""
+        UPDATE odyssey_journeys
+        SET
+            status = 'completed',
+            execution_result = %s,
+            updated_at = NOW()
+        WHERE key = %s
+          AND fencing_token = %s
+          AND status = 'executing'
+        RETURNING 1;
+        """, (serialized_result, key, fencing_token))
+
+        success = cur.fetchone() is not None
+
+    conn.commit()
+    return OperationResult(success)
+
+def abandon(conn, key, *, fencing_token):
+    with conn.cursor() as cur:
+        cur.execute("""
+        UPDATE odyssey_journeys
+        SET expires_at = NOW(),
+            updated_at = NOW()
+        WHERE key = %s
+            AND fencing_token = %s
+            AND status = 'executing'
+        RETURNING 1;
+        """, (key, fencing_token))
+        success = cur.fetchone() is not None
+
+    conn.commit()
+    return OperationResult(success)
+
+def inspect(conn, key):
+    with conn.cursor() as cur:
+        cur.execute("""
+        SELECT owner_id, expires_at, updated_at, fencing_token, status, 
+        expires_at > NOW() AS journey_alive, execution_result
+        FROM odyssey_journeys
+        WHERE key = %s 
+        """, (key,))
+
+        result = cur.fetchone()
+
+        if result is None:
+            return None
+
+        row = row_to_dict(cur, result)
+
+    return InspectResult(
+        key = key,
+        owner_id = row["owner_id"],
+        fencing_token = row["fencing_token"],
+        status = row["status"],
+        journey_alive = row["journey_alive"],
+        expires_at = row["expires_at"],
+        updated_at = row["updated_at"],
+        execution_result = row["execution_result"])

odyssey/results.py

@@ -0,0 +1,29 @@
+# Response structure of acquire
+class AcquireResult:
+    def __init__(self, acquired, owner_id=None, expires_at=None, fencing_token=None, status=None, journey_alive=None):
+        self.acquired = acquired
+        self.owner_id = owner_id
+        self.expires_at = expires_at
+        self.fencing_token = fencing_token
+        self.status = status
+        self.journey_alive = journey_alive
+
+class OperationResult:
+    def __init__(self, success: bool, status=None):
+        self.success = success
+        self.status = status
+
+class InspectResult:
+    def __init__(
+        self, key, owner_id, fencing_token, status, journey_alive, 
+        expires_at, updated_at, execution_result=None
+    ):
+        self.key = key
+        self.owner_id = owner_id
+        self.fencing_token = fencing_token
+        self.status = status
+        self.journey_alive = journey_alive
+        self.expires_at = expires_at
+        self.updated_at = updated_at
+        self.execution_result = execution_result
+        

odyssey/schema.py

@@ -0,0 +1,78 @@
+SCHEMA_SQL = """
+CREATE SEQUENCE IF NOT EXISTS odyssey_token_seq;
+
+DO $$
+BEGIN
+    CREATE TYPE odyssey_status AS ENUM (
+        'claimed',
+        'executing',
+        'completed',
+        'reconciling'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+
+DO $$
+BEGIN
+    CREATE TYPE odyssey_execution_mode AS ENUM (
+        'local',
+        'delegated'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+
+DO $$
+BEGIN
+    CREATE TYPE delivery_status AS ENUM (
+        'delivered',
+        'failed',
+        'pending'
+    );
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+
+CREATE TABLE IF NOT EXISTS odyssey_ledger (
+    key TEXT NOT NULL,
+    target TEXT NOT NULL,
+    status odyssey_status NOT NULL DEFAULT 'claimed',
+    mode odyssey_execution_mode NOT NULL,
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+
+    PRIMARY KEY (key, target)
+);
+
+CREATE TABLE IF NOT EXISTS odyssey_journeys (
+    key TEXT NOT NULL,
+    target TEXT NOT NULL,
+    owner_id TEXT NOT NULL,
+    expires_at TIMESTAMPTZ NOT NULL,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    execution_result JSONB,
+    status odyssey_status NOT NULL DEFAULT 'claimed',
+    fencing_token BIGINT NOT NULL DEFAULT 1,
+
+    PRIMARY KEY (key, target),
+    FOREIGN KEY (key, target)
+        REFERENCES odyssey_ledger(key, target)
+);
+
+CREATE TABLE IF NOT EXISTS odyssey_deliveries (
+    key TEXT NOT NULL,
+    target TEXT NOT NULL,
+    emit_to TEXT NOT NULL,
+    payload JSONB,
+    status delivery_status NOT NULL DEFAULT 'pending',
+    attempts INTEGER NOT NULL DEFAULT 0,
+    last_attempt_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    PRIMARY KEY (key, target, emit_to),
+    FOREIGN KEY (key, target)
+        REFERENCES odyssey_ledger(key, target)
+);
+"""

odyssey/utils.py

@@ -0,0 +1,14 @@
+import os
+import threading
+import socket
+
+def get_owner_id():
+    hostname = socket.gethostname()
+    pid = os.getpid()
+    thread_id = threading.get_ident()
+
+    return f"{hostname}:{pid}-{thread_id}"
+
+def row_to_dict(cursor, row):
+    columns = [desc[0] for desc in cursor.description]
+    return dict(zip(columns, row))

odysseys_py-0.0.1.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: odysseys-py
+Version: 0.0.1
+Summary: A lightweight durable execution and orchestration runtime for distributed services.
+Author: Sreejay Reddy
+License: MIT
+Keywords: workflow,durable-execution,orchestration,distributed-systems,postgres
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.0

odysseys_py-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+odyssey/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+odyssey/async_core.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+odyssey/async_odyssey.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+odyssey/build_ledger.py,sha256=-DmySjYLEiP-xukcXiUbTV-DQhE3qabdDg0kSDpKpzc,2005
+odyssey/config.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+odyssey/core.py,sha256=oDK14R9gA7vwmcTKaYDTZE-mXCq9sk_B4YX8Fa2s3Xk,5012
+odyssey/odyssey.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+odyssey/results.py,sha256=f-9ow7aIk-iIMeXlGPGSlwFTOcuvIjwAbIIhR4qlk5g,1027
+odyssey/schema.py,sha256=QKnym3QD3HD9lHEi8g4HRCU2bzvehBcO319NBWWRxR0,1909
+odyssey/utils.py,sha256=0013Y9rpQVpFV7gPEEOVHzuvIbECIyA-913pVISyua8,335
+odysseys_py-0.0.1.dist-info/METADATA,sha256=r9dErkINTHdjEauwjHAylvtgmyRv2fyU9xwqnoWOY2Q,831
+odysseys_py-0.0.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+odysseys_py-0.0.1.dist-info/top_level.txt,sha256=VLIR-rNWvsxwTiHp8C7gv3FqFDgiRTGlrYb-pVOgLoo,8
+odysseys_py-0.0.1.dist-info/RECORD,,

odysseys_py-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

odysseys_py-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+odyssey