koi-net 1.2.4__py3-none-any.whl

koi_net/__init__.py

@@ -0,0 +1 @@
+from . import log_system

koi_net/behaviors/handshaker.py

@@ -0,0 +1,68 @@
+import structlog
+from rid_lib.ext import Cache
+from rid_lib.types import KoiNetNode
+
+from ..network.graph import NetworkGraph
+from ..config.core import NodeConfig
+from ..identity import NodeIdentity
+from ..network.event_queue import EventQueue
+from ..protocol.event import Event, EventType
+
+log = structlog.stdlib.get_logger()
+
+
+class Handshaker:
+    """Handles handshaking with other nodes."""
+    def __init__(
+        self, 
+        cache: Cache, 
+        identity: NodeIdentity, 
+        event_queue: EventQueue,
+        config: NodeConfig,
+        graph: NetworkGraph
+    ):
+        self.config = config
+        self.cache = cache
+        self.identity = identity
+        self.event_queue = event_queue
+        self.graph = graph
+        
+    def start(self):
+        """Attempts handshake with first contact on startup.
+        
+        Handshake occurs if first contact is set in the config, the first
+        contact is not already known to this node, and this node does not
+        already have incoming edges with node providers.
+        """
+        if not self.config.koi_net.first_contact.rid:
+            return
+        
+        if self.cache.read(self.config.koi_net.first_contact.rid):
+            return
+        
+        if self.graph.get_neighbors(
+            direction="in", allowed_type=KoiNetNode):
+            return
+        
+        self.handshake_with(self.config.koi_net.first_contact.rid)
+        
+    def handshake_with(self, target: KoiNetNode):
+        """Initiates a handshake with target node.
+        
+        Pushes successive `FORGET` and `NEW` events to target node to
+        reset the target's cache in case it already knew this node. 
+        """
+        
+        log.debug(f"Initiating handshake with {target}")
+        self.event_queue.push(
+            Event.from_rid(
+                event_type=EventType.FORGET, 
+                rid=self.identity.rid),
+            target=target
+        )
+        self.event_queue.push(
+            event=Event.from_bundle(
+                event_type=EventType.NEW, 
+                bundle=self.cache.read(self.identity.rid)),
+            target=target
+        )

koi_net/behaviors/profile_monitor.py

@@ -0,0 +1,23 @@
+from rid_lib.ext import Bundle
+from ..identity import NodeIdentity
+from ..processor.kobj_queue import KobjQueue
+
+
+class ProfileMonitor:
+    """Processes changes to node profile in the config."""
+    def __init__(
+        self,
+        kobj_queue: KobjQueue,
+        identity: NodeIdentity
+    ):
+        self.kobj_queue = kobj_queue
+        self.identity = identity
+        
+    def start(self):
+        """Processes identity bundle generated from config."""
+        self_bundle = Bundle.generate(
+            rid=self.identity.rid,
+            contents=self.identity.profile.model_dump()
+        )
+        
+        self.kobj_queue.push(bundle=self_bundle)

koi_net/behaviors/sync_manager.py

@@ -0,0 +1,68 @@
+import structlog
+from rid_lib.ext import Cache
+from rid_lib.types import KoiNetNode
+
+from ..exceptions import RequestError
+from ..network.graph import NetworkGraph
+from ..network.request_handler import RequestHandler
+from ..processor.kobj_queue import KobjQueue
+from ..protocol.node import NodeProfile, NodeType
+
+log = structlog.stdlib.get_logger()
+
+
+class SyncManager:
+    """Handles state synchronization actions with other nodes."""
+    graph: NetworkGraph
+    cache: Cache
+    request_handler: RequestHandler
+    kobj_queue: KobjQueue
+    
+    def __init__(
+        self,
+        graph: NetworkGraph,
+        cache: Cache,
+        request_handler: RequestHandler,
+        kobj_queue: KobjQueue
+    ):
+        self.graph = graph
+        self.cache = cache
+        self.request_handler = request_handler
+        self.kobj_queue = kobj_queue
+        
+    def start(self):
+        """Catches up with node providers on startup."""
+        
+        node_providers = self.graph.get_neighbors(
+            direction="in",
+            allowed_type=KoiNetNode
+        )
+        
+        if not node_providers:
+            return
+        
+        log.debug(f"Catching up with `orn:koi-net.node` providers: {node_providers}")
+        self.catch_up_with(node_providers, [KoiNetNode])
+    
+    def catch_up_with(self, nodes, rid_types):
+        """Catches up with the state of RID types within other nodes."""
+    
+        for node in nodes:
+            node_bundle = self.cache.read(node)
+            node_profile = node_bundle.validate_contents(NodeProfile)
+            
+            # can't catch up with partial nodes
+            if node_profile.node_type != NodeType.FULL:
+                continue
+            
+            try:
+                payload = self.request_handler.fetch_manifests(
+                    node, rid_types=rid_types)
+            except RequestError:
+                continue
+            
+            for manifest in payload.manifests:
+                self.kobj_queue.push(
+                    manifest=manifest,
+                    source=node
+                )

koi_net/build/artifact.py

@@ -0,0 +1,209 @@
+import inspect
+from collections import deque
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from ..exceptions import BuildError
+from .consts import (
+    COMP_ORDER_OVERRIDE,
+    COMP_TYPE_OVERRIDE, 
+    START_FUNC_NAME, 
+    START_ORDER_OVERRIDE, 
+    STOP_FUNC_NAME, 
+    STOP_ORDER_OVERRIDE,
+    CompOrder,
+    CompType
+)
+
+if TYPE_CHECKING:
+    from .assembler import NodeAssembler
+
+log = structlog.stdlib.get_logger()
+
+
+class BuildArtifact:
+    assembler: "NodeAssembler"
+    comp_dict: dict[str, Any]
+    dep_graph: dict[str, list[str]]
+    comp_types: dict[str, CompType]
+    init_order: list[str]
+    start_order: list[str]
+    stop_order: list[str]
+    graphviz: str
+    
+    def __init__(self, assembler: "NodeAssembler"):
+        self.assembler = assembler
+        
+    def collect_comps(self):
+        """Collects components from class definition."""
+        
+        self.comp_dict = {}
+        # adds components from class and all base classes. skips `type`, and runs in reverse so that sub classes override super class values
+        for base in reversed(inspect.getmro(self.assembler)[:-1]):
+            for k, v in vars(base).items():
+                # excludes built in, private, and `None` attributes
+                if k.startswith("_") or v is None:
+                    continue
+                
+                self.comp_dict[k] = v
+        log.debug(f"Collected {len(self.comp_dict)} components")
+    
+    def build_dependencies(self):
+        """Builds dependency graph and component type map.
+        
+        Graph representation is an adjacency list: the key is a component 
+        name, and the value is a tuple containing names of the depedencies.
+        """
+        
+        self.comp_types = {}
+        self.dep_graph = {}
+        for comp_name, comp in self.comp_dict.items():
+            
+            dep_names = []
+            
+            explicit_type = getattr(comp, COMP_TYPE_OVERRIDE, None)
+            if explicit_type:
+                self.comp_types[comp_name] = explicit_type
+            
+            # non callable components are objects treated "as is"
+            elif not callable(comp):
+                self.comp_types[comp_name] = CompType.OBJECT
+            
+            # callable components default to singletons
+            else:
+                sig = inspect.signature(comp)
+                self.comp_types[comp_name] = CompType.SINGLETON
+                dep_names = list(sig.parameters)
+                
+                invalid_deps = set(dep_names) - set(self.comp_dict)
+                if invalid_deps:
+                    raise BuildError(f"Dependencies {invalid_deps} of component '{comp_name}' are undefined")
+                
+            self.dep_graph[comp_name] = dep_names
+        
+        log.debug("Built dependency graph")
+    
+    def build_init_order(self):
+        """Builds component initialization order using Kahn's algorithm."""
+        
+        # adj list: n -> outgoing neighbors
+        adj = self.dep_graph
+        # reverse adj list: n -> incoming neighbors
+        r_adj: dict[str, list[str]] = {}
+        
+        # computes reverse adjacency list
+        for node in adj:
+            r_adj.setdefault(node, [])
+            for n in adj[node]:
+                r_adj.setdefault(n, [])
+                r_adj[n].append(node)
+        
+        # how many outgoing edges each node has
+        out_degree = {
+            n: len(neighbors) 
+            for n, neighbors in adj.items()
+        }
+        
+        # initializing queue: nodes w/o dependencies
+        queue = deque()
+        for node in out_degree:
+            if out_degree[node] == 0:
+                queue.append(node)
+        
+        self.init_order = []
+        while queue:
+            # removes node from graph
+            n = queue.popleft()
+            self.init_order.append(n)
+            
+            # updates out degree for nodes dependent on this node
+            for next_n in r_adj[n]:
+                out_degree[next_n] -= 1
+                # adds nodes now without dependencies to queue
+                if out_degree[next_n] == 0:
+                    queue.append(next_n)
+        
+        if len(self.init_order) != len(self.dep_graph):
+            cycle_nodes = set(self.dep_graph) - set(self.init_order)
+            raise BuildError(f"Found cycle in dependency graph, the following nodes could not be ordered: {cycle_nodes}")
+        
+        log.debug(f"Resolved initialization order: {' -> '.join(self.init_order)}")
+        
+    def build_start_order(self):
+        """Builds component start order.
+        
+        Checks if components define a start function in init order. Can
+        be overridden by setting start order override in the `NodeAssembler`.
+        """
+        
+        self.start_order = getattr(self.assembler, START_ORDER_OVERRIDE, None)
+        
+        if self.start_order:
+            return
+        
+        workers = []
+        start_order = []
+        for comp_name in self.init_order:
+            comp = self.comp_dict[comp_name]
+            if getattr(comp, START_FUNC_NAME, None):
+                if getattr(comp, COMP_ORDER_OVERRIDE, None) == CompOrder.WORKER:
+                    workers.append(comp_name)
+                else:
+                    start_order.append(comp_name) 
+        
+        # order workers first
+        self.start_order = workers + start_order
+        
+        log.debug(f"Resolved start order: {' -> '.join(self.start_order)}")
+        
+    def build_stop_order(self):
+        """Builds component stop order.
+        
+        Checks if components define a stop function in init order. Can
+        be overridden by setting stop order override in the `NodeAssembler`.
+        """
+        self.stop_order = getattr(self.assembler, STOP_ORDER_OVERRIDE, None)
+        
+        if self.stop_order:
+            return
+        
+        workers = []
+        stop_order = []
+        for comp_name in self.init_order:
+            comp = self.comp_dict[comp_name]
+            if getattr(comp, STOP_FUNC_NAME, None):
+                if getattr(comp, COMP_ORDER_OVERRIDE, None) == CompOrder.WORKER:
+                    workers.append(comp_name)
+                else:
+                    stop_order.append(comp_name) 
+        
+        # order workers first (last)
+        self.stop_order = workers + stop_order
+        # reverse order from start order
+        self.stop_order.reverse()
+        
+        log.debug(f"Resolved stop order: {' -> '.join(self.stop_order)}")
+
+    def visualize(self) -> str:
+        """Creates representation of dependency graph in Graphviz DOT language."""
+        
+        s = "digraph G {\n"
+        for node, neighbors in self.dep_graph.items():
+            sub_s = node
+            if neighbors:
+                sub_s += f"-> {', '.join(neighbors)}"
+            sub_s = sub_s.replace("graph", "graph_") + ";"
+            s += " " * 4 + sub_s + "\n"
+        s += "}"
+        self.graphviz = s
+    
+    def build(self):
+        log.debug("Creating build artifact...")
+        self.collect_comps()
+        self.build_dependencies()
+        self.build_init_order()
+        self.build_start_order()
+        self.build_stop_order()
+        self.visualize()
+        log.debug("Done")

koi_net/build/assembler.py

@@ -0,0 +1,60 @@
+
+from typing import Any, Self
+
+import structlog
+
+from ..exceptions import BuildError
+from .artifact import BuildArtifact, CompType
+from .container import NodeContainer
+
+log = structlog.stdlib.get_logger()
+
+
+class NodeAssembler:
+    _artifact: BuildArtifact = None
+    
+    # optional order overrides:
+    _start_order: list[str]
+    _stop_order: list[str]
+    
+    # annotation hack to show the components and container methods
+    def __new__(cls) -> Self | NodeContainer:
+        """Returns assembled node container."""
+        
+        log.debug(f"Assembling '{cls.__name__}'")
+        
+        # builds assembly artifact if it doesn't exist
+        if not cls._artifact:
+            cls._artifact = BuildArtifact(cls)
+            cls._artifact.build()
+        
+        components = cls._build_components(cls._artifact)
+        
+        log.debug("Returning assembled node")
+        return NodeContainer(cls._artifact, **components)
+    
+    @staticmethod
+    def _build_components(artifact: BuildArtifact):
+        """Returns assembled components as a dict."""
+        
+        log.debug("Building components...")
+        components: dict[str, Any] = {}
+        for comp_name in artifact.init_order:
+        # for comp_name, (comp_type, dep_names) in dep_graph.items():
+            comp = artifact.comp_dict[comp_name]
+            comp_type = artifact.comp_types[comp_name]
+            
+            if comp_type == CompType.OBJECT:
+                components[comp_name] = comp
+            
+            elif comp_type == CompType.SINGLETON:
+                # builds depedency dict for current component
+                dependencies = {}
+                for dep in artifact.dep_graph[comp_name]:
+                    if dep not in components:
+                        raise BuildError(f"Couldn't find required component '{dep}'")
+                    dependencies[dep] = components[dep]
+                components[comp_name] = comp(**dependencies)
+        log.debug("Done")
+        
+        return components

koi_net/build/comp_order.py

@@ -0,0 +1,6 @@
+from .consts import COMP_ORDER_OVERRIDE, CompOrder
+
+
+def worker(cls):
+    setattr(cls, COMP_ORDER_OVERRIDE, CompOrder.WORKER)
+    return cls

koi_net/build/comp_type.py

@@ -0,0 +1,7 @@
+from .consts import COMP_TYPE_OVERRIDE, CompType
+
+
+def object(cls):
+    """Sets a component's type to `CompType.OBJECT`."""
+    setattr(cls, COMP_TYPE_OVERRIDE, CompType.OBJECT)
+    return cls

koi_net/build/consts.py

@@ -0,0 +1,18 @@
+from enum import StrEnum
+
+
+START_FUNC_NAME = "start"
+STOP_FUNC_NAME = "stop"
+
+START_ORDER_OVERRIDE = "_start_order"
+STOP_ORDER_OVERRIDE = "_stop_order"
+
+COMP_TYPE_OVERRIDE = "_comp_type"
+COMP_ORDER_OVERRIDE = "_comp_order"
+
+class CompType(StrEnum):
+    SINGLETON = "SINGLETON"
+    OBJECT = "OBJECT"
+
+class CompOrder(StrEnum):
+    WORKER = "WORKER"

koi_net/build/container.py

@@ -0,0 +1,46 @@
+import structlog
+
+from ..entrypoints.base import EntryPoint
+from .artifact import BuildArtifact
+from .consts import START_FUNC_NAME, STOP_FUNC_NAME
+
+log = structlog.stdlib.get_logger()
+
+
+class NodeContainer:
+    """Dummy 'shape' for node containers built by assembler."""
+    _artifact: BuildArtifact
+    
+    entrypoint: EntryPoint
+    
+    def __init__(self, artifact, **kwargs):
+        self._artifact = artifact
+        
+        # adds all components as attributes of this instance
+        for name, comp in kwargs.items():
+            setattr(self, name, comp)
+    
+    def run(self):
+        try:
+            self.start()
+            self.entrypoint.run()
+        except KeyboardInterrupt:
+            log.info("Keyboard interrupt!")
+        finally:
+            self.stop()
+    
+    def start(self):
+        log.info("Starting node...")
+        for comp_name in self._artifact.start_order:
+            comp = getattr(self, comp_name)
+            start_func = getattr(comp, START_FUNC_NAME)
+            log.info(f"Starting {comp_name}...")
+            start_func()
+            
+    def stop(self):
+        log.info("Stopping node...")
+        for comp_name in self._artifact.stop_order:
+            comp = getattr(self, comp_name)
+            stop_func = getattr(comp, STOP_FUNC_NAME)
+            log.info(f"Stopping {comp_name}...")
+            stop_func()

koi_net/cache.py

@@ -0,0 +1,81 @@
+import os
+import shutil
+from rid_lib.core import RID, RIDType
+from rid_lib.ext import Bundle
+from rid_lib.ext.utils import b64_encode, b64_decode
+
+from .config.core import NodeConfig
+
+
+class Cache:
+    def __init__(self, config: NodeConfig):
+        self.config = config
+        
+    @property
+    def directory_path(self):
+        return self.config.koi_net.cache_directory_path
+        
+    def file_path_to(self, rid: RID) -> str:
+        encoded_rid_str = b64_encode(str(rid))
+        return f"{self.directory_path}/{encoded_rid_str}.json"
+
+    def write(self, bundle: Bundle) -> Bundle:
+        """Writes bundle to cache, returns a Bundle."""
+        if not os.path.exists(self.directory_path):
+            os.makedirs(self.directory_path)
+            
+        with open(
+            file=self.file_path_to(bundle.manifest.rid), 
+            mode="w", 
+            encoding="utf-8"
+        ) as f:
+            f.write(bundle.model_dump_json(indent=2))
+
+        return bundle
+    
+    def exists(self, rid: RID) -> bool:
+        return os.path.exists(
+            self.file_path_to(rid)
+        )
+
+    def read(self, rid: RID) -> Bundle | None:
+        """Reads and returns CacheEntry from RID cache."""
+        try:
+            with open(
+                file=self.file_path_to(rid), 
+                mode="r",
+                encoding="utf-8"
+            ) as f:
+                return Bundle.model_validate_json(f.read())
+        except FileNotFoundError:
+            return None
+    
+    def list_rids(self, rid_types: list[RIDType] | None = None) -> list[RID]:
+        if not os.path.exists(self.directory_path):
+            return []
+        
+        rids = []
+        for filename in os.listdir(self.directory_path):
+            encoded_rid_str = filename.split(".")[0]
+            rid_str = b64_decode(encoded_rid_str)
+            rid = RID.from_string(rid_str)
+            
+            if not rid_types or type(rid) in rid_types:
+                rids.append(rid)
+            
+        return rids
+                
+    def delete(self, rid: RID) -> None:
+        """Deletes cache bundle."""
+        try:
+            os.remove(self.file_path_to(rid))
+        except FileNotFoundError:
+            return
+
+    def drop(self) -> None:
+        """Deletes all cache bundles."""
+        try:
+            shutil.rmtree(self.directory_path)
+        except FileNotFoundError:
+            return
+