koi-net 1.2.0b1__tar.gz → 1.2.0b3__tar.gz

{koi_net-1.2.0b1 → koi_net-1.2.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: koi-net
-Version: 1.2.0b1
+Version: 1.2.0b3
 Summary: Implementation of KOI-net protocol in Python
 Project-URL: Homepage, https://github.com/BlockScience/koi-net/
 Author-email: Luke Miller <luke@block.science>
@@ -36,6 +36,7 @@ Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=14.1.0
 Requires-Dist: rid-lib>=3.2.7
 Requires-Dist: ruamel-yaml>=0.18.10
+Requires-Dist: structlog>=25.4.0
 Requires-Dist: uvicorn>=0.34.2
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'

{koi_net-1.2.0b1 → koi_net-1.2.0b3}/examples/coordinator.py

@@ -1,11 +1,15 @@
 import logging
 from rich.logging import RichHandler
-from pydantic import Field
 from rid_lib.types import KoiNetNode, KoiNetEdge
-from koi_net.config import NodeConfig, KoiNetConfig, ServerConfig
-from koi_net.core import NodeAssembler
-from koi_net.protocol.node import NodeProfile, NodeProvides, NodeType
-from koi_net.context import HandlerContext
+from koi_net.config.full_node import (
+    FullNodeConfig, 
+    ServerConfig, 
+    KoiNetConfig, 
+    NodeProfile, 
+    NodeProvides
+)
+from koi_net.core import FullNode
+from koi_net.processor.context import HandlerContext
 from koi_net.processor.handler import HandlerType, KnowledgeHandler
 from koi_net.processor.knowledge_object import KnowledgeObject
 from koi_net.protocol.event import Event, EventType
@@ -22,22 +26,17 @@ logging.getLogger("koi_net").setLevel(logging.DEBUG)
 logger = logging.getLogger(__name__)
 
 
-class CoordinatorConfig(NodeConfig):
-    server: ServerConfig = Field(default_factory=lambda: 
-        ServerConfig(port=8080)
-    )
-    koi_net: KoiNetConfig = Field(default_factory = lambda:
-        KoiNetConfig(
-            node_name="coordinator",
-            node_profile=NodeProfile(
-                node_type=NodeType.FULL,
-                provides=NodeProvides(
-                    event=[KoiNetNode, KoiNetEdge],
-                    state=[KoiNetNode, KoiNetEdge]
-                )
-            ),
-            rid_types_of_interest=[KoiNetNode, KoiNetEdge]
-        )
+class CoordinatorConfig(FullNodeConfig):
+    server: ServerConfig = ServerConfig(port=8080)
+    koi_net: KoiNetConfig = KoiNetConfig(
+        node_name="coordinator",
+        node_profile=NodeProfile(
+            provides=NodeProvides(
+                event=[KoiNetNode, KoiNetEdge],
+                state=[KoiNetNode, KoiNetEdge]
+            )
+        ),
+        rid_types_of_interest=[KoiNetNode, KoiNetEdge]
     )
 
 @KnowledgeHandler.create(
@@ -52,7 +51,7 @@ def handshake_handler(ctx: HandlerContext, kobj: KnowledgeObject):
         
     logger.info("Sharing this node's bundle with peer")
     identity_bundle = ctx.cache.read(ctx.identity.rid)
-    ctx.event_queue.push_event_to(
+    ctx.event_queue.push(
         event=Event.from_bundle(EventType.NEW, identity_bundle),
         target=kobj.rid
     )
@@ -67,17 +66,13 @@ def handshake_handler(ctx: HandlerContext, kobj: KnowledgeObject):
         rid_types=[KoiNetNode, KoiNetEdge]
     )
         
-    ctx.kobj_queue.put_kobj(rid=edge_bundle.rid, event_type=EventType.FORGET)
-    ctx.kobj_queue.put_kobj(bundle=edge_bundle)
+    ctx.kobj_queue.push(rid=edge_bundle.rid, event_type=EventType.FORGET)
+    ctx.kobj_queue.push(bundle=edge_bundle)
 
-class CoordinatorNodeAssembler(NodeAssembler):
+class CoordinatorNode(FullNode):
     config = CoordinatorConfig
-    knowledge_handlers = [
-        *NodeAssembler.knowledge_handlers,
-        handshake_handler
-    ]
-
+    knowledge_handlers = FullNode.knowledge_handlers + [handshake_handler]
 
 if __name__ == "__main__":
-    node = CoordinatorNodeAssembler.create()
-    node.server.run()
+    node = CoordinatorNode()
+    node.entrypoint.run()

koi_net-1.2.0b3/examples/partial.py

@@ -0,0 +1,30 @@
+import logging
+from rich.logging import RichHandler
+from koi_net.config.partial_node import PartialNodeConfig, KoiNetConfig, NodeProfile
+from koi_net.core import PartialNode
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[RichHandler()]
+)
+
+logging.getLogger("koi_net").setLevel(logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+
+class MyPartialNodeConfig(PartialNodeConfig):
+    koi_net: KoiNetConfig = KoiNetConfig(
+        node_name="partial",
+        node_profile=NodeProfile()
+    )
+
+class MyPartialNode(PartialNode):
+    config_cls = MyPartialNodeConfig
+
+
+if __name__ == "__main__":
+    node = MyPartialNode()
+    # node.entrypoint.run()

{koi_net-1.2.0b1 → koi_net-1.2.0b3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "koi-net"
-version = "1.2.0b1"
+version = "1.2.0b3"
 description = "Implementation of KOI-net protocol in Python"
 authors = [
     {name = "Luke Miller", email = "luke@block.science"}
@@ -23,6 +23,7 @@ dependencies = [
     "fastapi>=0.115.12",
     "uvicorn>=0.34.2",
     "rich>=14.1.0",
+    "structlog>=25.4.0",
 ]
 
 [project.optional-dependencies]

koi_net-1.2.0b3/src/koi_net/__init__.py

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

koi_net-1.2.0b3/src/koi_net/assembler.py

@@ -0,0 +1,95 @@
+import inspect
+from typing import Protocol
+from dataclasses import make_dataclass
+
+from pydantic import BaseModel
+import structlog
+
+from .entrypoints.base import EntryPoint
+
+log = structlog.stdlib.get_logger()
+
+
+class BuildOrderer(type):
+    def __new__(cls, name: str, bases: tuple, dct: dict[str]):
+        """Sets `cls._build_order` from component order in class definition."""
+        cls = super().__new__(cls, name, bases, dct)
+        
+        if "_build_order" not in dct:
+            components = {}
+            # adds components from base classes (including cls)
+            for base in reversed(inspect.getmro(cls)[:-1]):
+                for k, v in vars(base).items():
+                    # excludes built in and private attributes
+                    if not k.startswith("_"):
+                        components[k] = v
+                        
+            # recipe list constructed from names of non-None components
+            cls._build_order = [
+                name for name, _type in components.items()
+                if _type is not None
+            ]
+            
+        return cls
+
+class NodeContainer(Protocol):
+    entrypoint = EntryPoint
+
+class NodeAssembler(metaclass=BuildOrderer):    
+    def __new__(self) -> NodeContainer:
+        return self._build()
+    
+    @classmethod
+    def _build(cls) -> NodeContainer:
+        components = {}
+        for comp_name in cls._build_order:
+            comp = getattr(cls, comp_name, None)
+            
+            if comp is None:
+                raise Exception(f"Couldn't find factory for component '{comp_name}'")
+            
+            print(comp_name)
+            
+            if not callable(comp):
+                print(f"Treating {comp_name} as a literal")
+                components[comp_name] = comp
+                continue
+            
+            if issubclass(comp, BaseModel):
+                print(f"Treating {comp_name} as a pydantic model")
+                components[comp_name] = comp
+                continue
+            
+            sig = inspect.signature(comp)
+            
+            required_comps = []
+            for name, param in sig.parameters.items():
+                required_comps.append((name, param.annotation))
+            
+            if len(required_comps) == 0:
+                s = comp_name
+            else:
+                s = f"{comp_name} -> {', '.join([name for name, _type in required_comps])}"
+            
+            # print(s.replace("graph", "_graph"), end=";\n")
+            
+            dependencies = {}
+            for req_comp_name, req_comp_type in required_comps:
+                if req_comp_name not in components:
+                    raise Exception(f"Couldn't find required component '{req_comp_name}'")
+                    
+                dependencies[req_comp_name] = components[req_comp_name]
+                
+            components[comp_name] = comp(**dependencies)
+        
+        NodeContainer = make_dataclass(
+            cls_name="NodeContainer",
+            fields=[
+                (name, type(component)) 
+                for name, component
+                in components.items()
+            ],
+            frozen=True
+        )
+        
+        return NodeContainer(**components)

{koi_net-1.2.0b1 → koi_net-1.2.0b3}/src/koi_net/cli/models.py

@@ -1,9 +1,9 @@
-from pydantic import BaseModel, Field, PrivateAttr
+from pydantic import BaseModel, PrivateAttr
 from ruamel.yaml import YAML
 
 
 class KoiNetworkConfig(BaseModel):
-    nodes: dict[str, str] = Field(default_factory=dict)
+    nodes: dict[str, str] = {}
     _file_path: str = PrivateAttr(default="koi-net-config.yaml")
 
     @classmethod

koi_net-1.2.0b3/src/koi_net/config/core.py

@@ -0,0 +1,71 @@
+import os
+from pydantic import BaseModel, model_validator
+from dotenv import load_dotenv
+from rid_lib import RIDType
+from rid_lib.types import KoiNetNode
+
+from koi_net.protocol.secure import PrivateKey
+from ..protocol.node import NodeProfile
+
+
+class NodeContact(BaseModel):
+    rid: KoiNetNode | None = None
+    url: str | None = None
+
+class KoiNetConfig(BaseModel):
+    """Config for KOI-net."""
+    
+    node_name: str
+    node_rid: KoiNetNode | None = None
+    node_profile: NodeProfile
+    
+    rid_types_of_interest: list[RIDType] = [KoiNetNode]
+        
+    cache_directory_path: str = ".rid_cache"
+    event_queues_path: str = "event_queues.json"
+    private_key_pem_path: str = "priv_key.pem"
+    
+    first_contact: NodeContact = NodeContact()
+    
+class EnvConfig(BaseModel):
+    """Config for environment variables.
+    
+    Values set in the config are the variables names, and are loaded
+    from the environment at runtime. For example, if the config YAML
+    sets `priv_key_password: PRIV_KEY_PASSWORD` accessing 
+    `priv_key_password` would retrieve the value of `PRIV_KEY_PASSWORD`
+    from the environment.
+    """
+    
+    priv_key_password: str = "PRIV_KEY_PASSWORD"
+    
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        load_dotenv()
+    
+    def __getattribute__(self, name):
+        value = super().__getattribute__(name)
+        if name in type(self).model_fields:
+            env_val = os.getenv(value)
+            if env_val is None:
+                raise ValueError(f"Required environment variable {value} not set")
+            return env_val
+        return value
+
+class NodeConfig(BaseModel):
+    koi_net: KoiNetConfig
+    env: EnvConfig = EnvConfig()
+    
+    @model_validator(mode="after")
+    def generate_rid_cascade(self):
+        if not self.koi_net.node_rid:
+            priv_key = PrivateKey.generate()
+            pub_key = priv_key.public_key()
+            
+            self.koi_net.node_rid = pub_key.to_node_rid(self.koi_net.node_name)
+            
+            with open(self.koi_net.private_key_pem_path, "w") as f:
+                f.write(priv_key.to_pem(self.env.priv_key_password))
+            
+            self.koi_net.node_profile.public_key = pub_key.to_der()
+        return self

koi_net-1.2.0b3/src/koi_net/config/full_node.py

@@ -0,0 +1,31 @@
+from pydantic import BaseModel, model_validator
+from koi_net.config.core import NodeConfig, KoiNetConfig as BaseKoiNetConfig
+from ..protocol.node import NodeProfile as BaseNodeProfile, NodeType, NodeProvides
+
+
+class NodeProfile(BaseNodeProfile):
+    node_type: NodeType = NodeType.FULL
+
+class KoiNetConfig(BaseKoiNetConfig):
+    node_profile: NodeProfile
+
+class ServerConfig(BaseModel):
+    """Config for the node server (full node only)."""
+    
+    host: str = "127.0.0.1"
+    port: int = 8000
+    path: str | None = "/koi-net"
+    
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}{self.path or ''}"
+
+class FullNodeConfig(NodeConfig):
+    koi_net: KoiNetConfig
+    server: ServerConfig = ServerConfig()
+    
+    @model_validator(mode="after")
+    def check_url(self):
+        if not self.koi_net.node_profile.base_url:
+            self.koi_net.node_profile.base_url = self.server.url
+        return self

koi_net-1.2.0b3/src/koi_net/config/loader.py

@@ -0,0 +1,46 @@
+from ruamel.yaml import YAML
+from .core import NodeConfig
+
+
+class ConfigLoader:
+    _config: NodeConfig
+    
+    _file_path: str = "config.yaml"
+    _file_content: str
+    
+    def __init__(self, config_cls: type[NodeConfig]):
+        self._config_cls = config_cls
+        self.load_from_yaml()
+    
+    def __getattr__(self, name):
+        return getattr(self._config, name)
+    
+    def load_from_yaml(self):
+        """Loads config state from YAML file."""
+        yaml = YAML()
+        
+        try:
+            with open(self._file_path, "r") as f:
+                self._file_content = f.read()
+            config_data = yaml.load(self._file_content)
+            self._config = self._config_cls.model_validate(config_data)
+        
+        except FileNotFoundError:
+            self._config = self._config_cls()
+        
+        self.save_to_yaml()
+        
+        
+    def save_to_yaml(self):
+        yaml = YAML()
+        
+        with open(self._file_path, "w") as f:
+            try:
+                config_data = self._config.model_dump(mode="json")
+                yaml.dump(config_data, f)
+            except Exception as e:
+                if self._file_content:
+                    f.seek(0)
+                    f.truncate()
+                    f.write(self._file_content)
+                raise e

koi_net-1.2.0b3/src/koi_net/config/partial_node.py

@@ -0,0 +1,18 @@
+from pydantic import BaseModel
+from koi_net.config.core import NodeConfig, KoiNetConfig
+from ..protocol.node import NodeProfile, NodeType, NodeProvides
+
+
+class NodeProfile(NodeProfile):
+    base_url: str | None = None
+    node_type: NodeType = NodeType.PARTIAL
+
+class KoiNetConfig(KoiNetConfig):
+    node_profile: NodeProfile    
+
+class PollerConfig(BaseModel):
+    polling_interval: int = 5
+
+class PartialNodeConfig(NodeConfig):
+    koi_net: KoiNetConfig
+    poller: PollerConfig = PollerConfig()

koi_net-1.2.0b3/src/koi_net/core.py

@@ -0,0 +1,70 @@
+from rid_lib.ext import Cache
+
+from .config.loader import ConfigLoader
+from .assembler import NodeAssembler
+from .config.core import NodeConfig
+from .processor.context import HandlerContext
+from .effector import Effector
+from .handshaker import Handshaker
+from .identity import NodeIdentity
+from .workers import KnowledgeProcessingWorker, EventProcessingWorker
+from .lifecycle import NodeLifecycle
+from .network.error_handler import ErrorHandler
+from .network.event_queue import EventQueue
+from .network.graph import NetworkGraph
+from .network.request_handler import RequestHandler
+from .network.resolver import NetworkResolver
+from .network.response_handler import ResponseHandler
+from .network.poll_event_buffer import PollEventBuffer
+from .processor.pipeline import KnowledgePipeline
+from .processor.kobj_queue import KobjQueue
+from .secure import Secure
+from .entrypoints import NodeServer, NodePoller
+from .processor.knowledge_handlers import (
+    basic_manifest_handler, 
+    basic_network_output_filter, 
+    basic_rid_handler, 
+    node_contact_handler, 
+    edge_negotiation_handler, 
+    forget_edge_on_node_deletion, 
+    secure_profile_handler
+)
+
+
+class BaseNode(NodeAssembler):
+    config_cls = NodeConfig
+    kobj_queue = KobjQueue
+    event_queue = EventQueue
+    poll_event_buf = PollEventBuffer
+    config = ConfigLoader
+    knowledge_handlers = [
+        basic_rid_handler,
+        basic_manifest_handler,
+        secure_profile_handler,
+        edge_negotiation_handler,
+        node_contact_handler,
+        basic_network_output_filter,
+        forget_edge_on_node_deletion
+    ]
+    cache = lambda config: Cache(
+        directory_path=config.koi_net.cache_directory_path)
+    identity = NodeIdentity
+    graph = NetworkGraph
+    secure = Secure
+    handshaker = Handshaker
+    error_handler = ErrorHandler
+    request_handler = RequestHandler
+    response_handler = ResponseHandler
+    resolver = NetworkResolver
+    effector = Effector
+    handler_context = HandlerContext
+    pipeline = KnowledgePipeline
+    kobj_worker = KnowledgeProcessingWorker
+    event_worker = EventProcessingWorker
+    lifecycle = NodeLifecycle
+
+class FullNode(BaseNode):
+    entrypoint = NodeServer
+
+class PartialNode(BaseNode):
+    entrypoint = NodePoller

{koi_net-1.2.0b1 → koi_net-1.2.0b3}/src/koi_net/default_actions.py

@@ -1,9 +1,8 @@
 """Implementations of default dereference actions."""
 
-from .context import ActionContext
 from rid_lib.types import KoiNetNode
 from rid_lib.ext import Bundle
-from .effector import Effector
+from .effector import Effector, ActionContext
 
 
 @Effector.register_default_action(KoiNetNode)

{koi_net-1.2.0b1 → koi_net-1.2.0b3}/src/koi_net/effector.py

@@ -1,4 +1,4 @@
-import logging
+import structlog
 from typing import Callable
 from enum import StrEnum
 from rid_lib.ext import Cache, Bundle
@@ -6,11 +6,23 @@ from rid_lib.core import RID, RIDType
 from rid_lib.types import KoiNetNode
 from .network.resolver import NetworkResolver
 from .processor.kobj_queue import KobjQueue
-from .context import ActionContext
+from .identity import NodeIdentity
 
-logger = logging.getLogger(__name__)
+log = structlog.stdlib.get_logger()
 
 
+class ActionContext:
+    """Provides action handlers access to other subsystems."""
+    
+    identity: NodeIdentity
+
+    def __init__(
+        self,
+        identity: NodeIdentity,
+    ):
+        self.identity = identity
+    
+
 class BundleSource(StrEnum):
     CACHE = "CACHE"
     ACTION = "ACTION"
@@ -35,12 +47,12 @@ class Effector:
         cache: Cache,
         resolver: NetworkResolver,
         kobj_queue: KobjQueue,
-        action_context: ActionContext
+        identity: NodeIdentity
     ):
         self.cache = cache
         self.resolver = resolver
         self.kobj_queue = kobj_queue
-        self.action_context = action_context
+        self.action_context = ActionContext(identity)
         self._action_table = self.__class__._action_table.copy()
     
     @classmethod
@@ -70,18 +82,18 @@ class Effector:
         bundle = self.cache.read(rid)
         
         if bundle:
-            logger.debug("Cache hit")
+            log.debug("Cache hit")
             return bundle, BundleSource.CACHE
         else:
-            logger.debug("Cache miss")
+            log.debug("Cache miss")
             return None
                     
     def _try_action(self, rid: RID) -> tuple[Bundle, BundleSource] | None:
         if type(rid) not in self._action_table:
-            logger.debug("No action available")
+            log.debug("No action available")
             return None
         
-        logger.debug("Action available")
+        log.debug("Action available")
         func = self._action_table[type(rid)]
         bundle = func(
             ctx=self.action_context, 
@@ -89,10 +101,10 @@ class Effector:
         )
         
         if bundle:
-            logger.debug("Action hit")
+            log.debug("Action hit")
             return bundle, BundleSource.ACTION
         else:
-            logger.debug("Action miss")
+            log.debug("Action miss")
             return None
 
         
@@ -100,10 +112,10 @@ class Effector:
         bundle, source = self.resolver.fetch_remote_bundle(rid)
         
         if bundle:
-            logger.debug("Network hit")
+            log.debug("Network hit")
             return bundle, source
         else:
-            logger.debug("Network miss")
+            log.debug("Network miss")
             return None
         
     
@@ -127,7 +139,7 @@ class Effector:
             handle_result: handles resulting bundle with knowledge pipeline when `True`
         """
         
-        logger.debug(f"Dereferencing {rid!r}")
+        log.debug(f"Dereferencing {rid!r}")
         
         bundle, source = (
             # if `refresh_cache`, skip try cache
@@ -143,7 +155,7 @@ class Effector:
             and bundle is not None 
             and source != BundleSource.CACHE
         ):            
-            self.kobj_queue.put_kobj(
+            self.kobj_queue.push(
                 bundle=bundle, 
                 source=source if type(source) is KoiNetNode else None
             )

koi_net-1.2.0b3/src/koi_net/entrypoints/__init__.py

@@ -0,0 +1,2 @@
+from .poller import NodePoller
+from .server import NodeServer

koi_net-1.2.0b3/src/koi_net/entrypoints/base.py

@@ -0,0 +1,5 @@
+from koi_net.config.core import NodeConfig
+
+
+class EntryPoint:
+    def run(self): ...