koi-net 1.2.4__py3-none-any.whl

koi_net/config/core.py

@@ -0,0 +1,113 @@
+import os
+from pydantic import BaseModel, model_validator
+from dotenv import load_dotenv
+from rid_lib import RIDType
+from rid_lib.types import KoiNetNode
+import structlog
+
+from ..build import comp_type
+from ..protocol.secure import PrivateKey
+from ..protocol.node import NodeProfile
+
+log = structlog.stdlib.get_logger()
+
+
+class EventWorkerConfig(BaseModel):
+    queue_timeout: float = 0.1
+    max_buf_len: int = 5
+    max_wait_time: float = 1.0
+    
+class KobjWorkerConfig(BaseModel):
+    queue_timeout: float = 0.1
+
+class NodeContact(BaseModel):
+    rid: KoiNetNode | None = None
+    url: str | None = None
+
+class KoiNetConfig(BaseModel):
+    """Config for KOI-net parameters."""
+    
+    node_name: str
+    node_rid: KoiNetNode | None = None
+    node_profile: NodeProfile
+    
+    rid_types_of_interest: list[RIDType] = [KoiNetNode]
+        
+    cache_directory_path: str = ".rid_cache"
+    private_key_pem_path: str = "priv_key.pem"
+    
+    event_worker: EventWorkerConfig = EventWorkerConfig()
+    kobj_worker: KobjWorkerConfig = KobjWorkerConfig()
+    
+    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 variables.
+    """
+    
+    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
+
+# marking this component as static, classes are implicitly treated as
+# factories, but this needs to be passed as is
+@comp_type.object
+class NodeConfig(BaseModel):
+    """Base node config class, intended to be extended."""
+    
+    koi_net: KoiNetConfig
+    env: EnvConfig = EnvConfig()
+    
+    @model_validator(mode="after")
+    def generate_rid_cascade(self):
+        """Generates node RID if missing."""
+        if self.koi_net.node_rid and self.koi_net.node_profile.public_key:
+            return self
+        
+        log.debug("Node RID or public key not found in config, attempting to generate")
+        
+        try:
+            # attempts to read existing private key PEM file
+            with open(self.koi_net.private_key_pem_path, "r") as f:
+                priv_key_pem = f.read()
+                priv_key = PrivateKey.from_pem(
+                    priv_key_pem,
+                    password=self.env.priv_key_password)
+                log.debug("Used existing private key from PEM file")
+        
+        except FileNotFoundError:
+            # generates new private key if PEM not found
+            priv_key = PrivateKey.generate()
+            
+            with open(self.koi_net.private_key_pem_path, "w") as f:
+                f.write(priv_key.to_pem(self.env.priv_key_password))
+            log.debug("Generated new private key, no PEM file found")
+        
+        pub_key = priv_key.public_key()
+        self.koi_net.node_rid = pub_key.to_node_rid(self.koi_net.node_name)
+        log.debug(f"Node RID set to {self.koi_net.node_rid}")
+        
+        if self.koi_net.node_profile.public_key != pub_key.to_der():
+            if self.koi_net.node_profile.public_key:
+                log.warning("New private key overwriting old public key!")
+            
+            self.koi_net.node_profile.public_key = pub_key.to_der()
+        
+        return self

koi_net/config/full_node.py

@@ -0,0 +1,45 @@
+from pydantic import BaseModel, model_validator
+from .core import NodeConfig, KoiNetConfig as BaseKoiNetConfig
+from ..protocol.node import (
+    NodeProfile as BaseNodeProfile, 
+    NodeType, 
+    NodeProvides
+)
+
+
+class NodeProfile(BaseNodeProfile):
+    """Node profile config class for full nodes."""
+    node_type: NodeType = NodeType.FULL
+
+class KoiNetConfig(BaseKoiNetConfig):
+    """KOI-net config class for full nodes."""
+    node_profile: NodeProfile
+
+class ServerConfig(BaseModel):
+    """Server config for full nodes.
+    
+    The parameters in this class represent how a server should be hosted,
+    not accessed. For example, a node may host a server at
+    `http://127.0.0.1:8000/koi-net`, but serve through nginx at
+    `https://example.com/koi-net`.
+    """
+    
+    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):
+    """Node config class for full nodes."""
+    koi_net: KoiNetConfig
+    server: ServerConfig = ServerConfig()
+    
+    @model_validator(mode="after")
+    def check_url(self):
+        """Generates base URL if missing from node profile."""
+        if not self.koi_net.node_profile.base_url:
+            self.koi_net.node_profile.base_url = self.server.url
+        return self

koi_net/config/loader.py

@@ -0,0 +1,60 @@
+from ruamel.yaml import YAML
+
+from .proxy import ConfigProxy
+from .core import NodeConfig
+
+
+class ConfigLoader:
+    """Loads node config from a YAML file, and proxies access to it."""
+    
+    file_path: str = "config.yaml"
+    file_content: str
+    
+    config_schema: type[NodeConfig]
+    proxy: ConfigProxy
+    
+    def __init__(
+        self, 
+        config_schema: type[NodeConfig],
+        config: ConfigProxy
+    ):
+        self.config_schema = config_schema
+        self.proxy = config
+        
+        # this is a special case to allow config state dependent components
+        # to initialize without a "lazy initialization" approach, in general
+        # components SHOULD NOT execute code in their init phase
+        self.load_from_yaml()
+        
+    def start(self):
+        self.save_to_yaml()
+    
+    def load_from_yaml(self):
+        """Loads config from YAML file, or generates it if missing."""
+        yaml = YAML()
+        
+        try:
+            with open(self.file_path, "r") as f:
+                self.file_content = f.read()
+            config_data = yaml.load(self.file_content)
+            self.proxy._config = self.config_schema.model_validate(config_data)
+        
+        except FileNotFoundError:
+            self.proxy._config = self.config_schema()
+        
+    def save_to_yaml(self):
+        """Saves config to YAML file."""
+        yaml = YAML()
+        
+        with open(self.file_path, "w") as f:
+            try:
+                config_data = self.proxy._config.model_dump(mode="json")
+                yaml.dump(config_data, f)
+                
+            except Exception:
+                # rewrites original content if YAML dump fails
+                if self.file_content:
+                    f.seek(0)
+                    f.truncate()
+                    f.write(self.file_content)
+                raise

koi_net/config/partial_node.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+from .core import NodeConfig, KoiNetConfig as BaseKoiNetConfig
+from ..protocol.node import (
+    NodeProfile as BaseNodeProfile, 
+    NodeType, 
+    NodeProvides
+)
+
+
+class NodeProfile(BaseNodeProfile):
+    """Node profile config class for partial nodes."""
+    base_url: str | None = None
+    node_type: NodeType = NodeType.PARTIAL
+
+class KoiNetConfig(BaseKoiNetConfig):
+    """KOI-net config class for partial nodes."""
+    node_profile: NodeProfile
+
+class PollerConfig(BaseModel):
+    """Poller config for partial nodes."""
+    polling_interval: int = 5
+
+class PartialNodeConfig(NodeConfig):
+    """Node config class for partial nodes."""
+    koi_net: KoiNetConfig
+    poller: PollerConfig = PollerConfig()

koi_net/config/proxy.py

@@ -0,0 +1,20 @@
+from .core import NodeConfig
+
+
+class ConfigProxy:
+    """Proxy for config access.
+    
+    Allows initialization of this component, and updating state without
+    destroying the original reference. Handled as if it were a config
+    model by other classes, loaded and saved by the `ConfigLoader`.
+    """
+    _config: NodeConfig
+    
+    def __init__(self):
+        self._config = None
+    
+    def __getattr__(self, name):
+        if not self._config:
+            raise RuntimeError("Proxy called before config loaded")
+            
+        return getattr(self._config, name)

koi_net/core.py

@@ -0,0 +1,78 @@
+from .cache import Cache
+from .build.assembler import NodeAssembler
+from .config.core import NodeConfig
+from .config.proxy import ConfigProxy
+from .config.loader import ConfigLoader
+from .config.full_node import FullNodeConfig
+from .config.partial_node import PartialNodeConfig
+from .processor.context import HandlerContext
+from .effector import DerefHandler, Effector
+from .behaviors.handshaker import Handshaker
+from .behaviors.sync_manager import SyncManager
+from .identity import NodeIdentity
+from .workers import KnowledgeProcessingWorker, EventProcessingWorker
+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.event_buffer import EventBuffer
+from .processor.pipeline import KnowledgePipeline
+from .processor.kobj_queue import KobjQueue
+from .processor.handler import KnowledgeHandler
+from .secure_manager import SecureManager
+from .behaviors.profile_monitor import ProfileMonitor
+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):
+    kobj_queue: KobjQueue = KobjQueue
+    event_queue: EventQueue = EventQueue
+    poll_event_buf: EventBuffer = EventBuffer
+    broadcast_event_buf: EventBuffer = EventBuffer
+    config_schema = NodeConfig
+    config: NodeConfig = ConfigProxy
+    config_loader: ConfigLoader = ConfigLoader
+    knowledge_handlers: list[KnowledgeHandler] = [
+        basic_rid_handler,
+        basic_manifest_handler,
+        secure_profile_handler,
+        edge_negotiation_handler,
+        node_contact_handler,
+        basic_network_output_filter,
+        forget_edge_on_node_deletion
+    ]
+    deref_handlers: list[DerefHandler] = []
+    cache: Cache = Cache
+    identity: NodeIdentity = NodeIdentity
+    graph: NetworkGraph = NetworkGraph
+    secure_manager: SecureManager = SecureManager
+    handshaker: Handshaker = Handshaker
+    error_handler: ErrorHandler = ErrorHandler
+    request_handler: RequestHandler = RequestHandler
+    sync_manager: SyncManager = SyncManager
+    response_handler: ResponseHandler = ResponseHandler
+    resolver: NetworkResolver = NetworkResolver
+    handler_context: HandlerContext = HandlerContext
+    effector: Effector = Effector
+    pipeline: KnowledgePipeline = KnowledgePipeline
+    kobj_worker: KnowledgeProcessingWorker = KnowledgeProcessingWorker
+    event_worker: EventProcessingWorker = EventProcessingWorker
+    profile_monitor: ProfileMonitor = ProfileMonitor
+
+class FullNode(BaseNode):
+    entrypoint: NodeServer = NodeServer
+    config: FullNodeConfig
+
+class PartialNode(BaseNode):
+    entrypoint: NodePoller = NodePoller
+    config: PartialNodeConfig

koi_net/effector.py

@@ -0,0 +1,147 @@
+from dataclasses import dataclass
+from typing import Callable
+from enum import StrEnum
+
+import structlog
+from rid_lib.ext import Cache, Bundle
+from rid_lib.core import RID, RIDType
+from rid_lib.types import KoiNetNode
+
+from .processor.context import HandlerContext
+from .network.resolver import NetworkResolver
+from .processor.kobj_queue import KobjQueue
+
+log = structlog.stdlib.get_logger()
+
+@dataclass
+class DerefHandler:
+    func: Callable[[HandlerContext, RID], Bundle | None]
+    rid_types: tuple[RIDType]
+    
+    def __call__(self, ctx: HandlerContext, rid: RID) -> Bundle | None:
+        return self.func(ctx, rid)
+    
+    @classmethod
+    def create(cls, rid_types: tuple[RIDType]):
+        def decorator(func: Callable) -> DerefHandler:
+            handler = cls(func, rid_types)
+            return handler
+        return decorator
+
+
+class BundleSource(StrEnum):
+    CACHE = "CACHE"
+    ACTION = "ACTION"
+
+class Effector:
+    """Subsystem for dereferencing RIDs."""
+    
+    cache: Cache
+    resolver: NetworkResolver
+    kobj_queue: KobjQueue
+    handler_context: HandlerContext
+    
+    def __init__(
+        self, 
+        cache: Cache,
+        resolver: NetworkResolver,
+        kobj_queue: KobjQueue,
+        handler_context: HandlerContext,
+        deref_handlers: list[DerefHandler]
+    ):
+        self.cache = cache
+        self.resolver = resolver
+        self.kobj_queue = kobj_queue
+        self.handler_context = handler_context
+        self.deref_handlers = deref_handlers
+        
+        self.handler_context.set_effector(self)
+    
+    def _try_cache(self, rid: RID) -> tuple[Bundle, BundleSource] | None:
+        bundle = self.cache.read(rid)
+        
+        if bundle:
+            log.debug("Cache hit")
+            return bundle, BundleSource.CACHE
+        else:
+            log.debug("Cache miss")
+            return None
+            
+    def _try_action(self, rid: RID) -> tuple[Bundle, BundleSource] | None:
+        action = None
+        for handler in self.deref_handlers:
+            if type(rid) not in handler.rid_types:
+                continue
+            action = handler
+            break
+        
+        if not action:
+            log.debug("No action found")
+            return None
+        
+        bundle = action(ctx=self.handler_context, rid=rid)
+        
+        if bundle:
+            log.debug("Action hit")
+            return bundle, BundleSource.ACTION
+        else:
+            log.debug("Action miss")
+            return None
+        
+    def _try_network(self, rid: RID) -> tuple[Bundle, KoiNetNode] | None:
+        bundle, source = self.resolver.fetch_remote_bundle(rid)
+        
+        if bundle:
+            log.debug("Network hit")
+            return bundle, source
+        else:
+            log.debug("Network miss")
+            return None
+        
+    def deref(
+        self, 
+        rid: RID,
+        refresh_cache: bool = False,
+        use_network: bool = False,
+        handle_result: bool = True,
+        write_through: bool = False
+    ) -> Bundle | None:
+        """Dereferences an RID.
+        
+        Attempts to dereference an RID by (in order) reading the cache, 
+        calling a bound action, or fetching from other nodes in the 
+        newtork.
+        
+        Args:
+            rid: RID to dereference
+            refresh_cache: skips cache read when `True` 
+            use_network: enables fetching from other nodes when `True`
+            handle_result: sends resulting bundle to kobj queue when `True`
+            write_through: waits for kobj queue to empty when `True`
+        """
+        
+        log.debug(f"Dereferencing {rid!r}")
+        
+        bundle, source = (
+            # if `refresh_cache`, skip try cache
+            not refresh_cache and self._try_cache(rid) or 
+            self._try_action(rid) or
+            use_network and self._try_network(rid) or
+            # if not found, bundle and source set to None
+            (None, None) 
+        )
+        
+        if (
+            handle_result 
+            and bundle is not None 
+            and source != BundleSource.CACHE
+        ):            
+            self.kobj_queue.push(
+                bundle=bundle, 
+                source=source if type(source) is KoiNetNode else None
+            )
+            
+            if write_through:
+                self.kobj_queue.q.join()
+                
+        return bundle

koi_net/entrypoints/__init__.py

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

koi_net/entrypoints/base.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+
+class EntryPoint(ABC):
+    """Abstract class for entry point components."""
+    @abstractmethod
+    def run(self): 
+        ...

koi_net/entrypoints/poller.py

@@ -0,0 +1,43 @@
+
+import time
+import structlog
+
+from .base import EntryPoint
+from ..processor.kobj_queue import KobjQueue
+from ..network.resolver import NetworkResolver
+from ..config.partial_node import PartialNodeConfig
+
+log = structlog.stdlib.get_logger()
+
+
+class NodePoller(EntryPoint):
+    """Entry point for partial nodes, manages polling event loop."""
+    kobj_queue: KobjQueue
+    resolver: NetworkResolver
+    config: PartialNodeConfig
+    
+    def __init__(
+        self,
+        config: PartialNodeConfig,
+        kobj_queue: KobjQueue,
+        resolver: NetworkResolver
+    ):
+        self.kobj_queue = kobj_queue
+        self.resolver = resolver
+        self.config = config
+
+    def poll(self):
+        """Polls neighbor nodes and processes returned events."""
+        for node_rid, events in self.resolver.poll_neighbors().items():
+            for event in events:
+                self.kobj_queue.push(event=event, source=node_rid)
+
+    def run(self):
+        """Runs polling event loop."""
+        while True:
+            start_time = time.time()
+            self.poll()
+            elapsed = time.time() - start_time
+            sleep_time = self.config.poller.polling_interval - elapsed
+            if sleep_time > 0:
+                time.sleep(sleep_time)

koi_net/entrypoints/server.py

@@ -0,0 +1,85 @@
+import structlog
+import uvicorn
+from fastapi import FastAPI, APIRouter
+from fastapi.responses import JSONResponse
+
+from .base import EntryPoint
+from ..network.response_handler import ResponseHandler
+from ..protocol.model_map import API_MODEL_MAP
+from ..protocol.api_models import ErrorResponse
+from ..protocol.errors import EXCEPTION_TO_ERROR_TYPE, ProtocolError
+from ..config.full_node import FullNodeConfig
+
+log = structlog.stdlib.get_logger()
+
+
+class NodeServer(EntryPoint):
+    """Entry point for full nodes, manages FastAPI server."""
+    config: FullNodeConfig
+    response_handler: ResponseHandler
+    app: FastAPI
+    router: APIRouter
+    
+    def __init__(
+        self,
+        config: FullNodeConfig,
+        response_handler: ResponseHandler,
+    ):
+        self.config = config
+        self.response_handler = response_handler
+        
+        self.build_app()
+        
+    def build_endpoints(self, router: APIRouter):
+        """Builds endpoints for API router."""
+        for path, models in API_MODEL_MAP.items():
+            def create_endpoint(path: str):
+                async def endpoint(req):
+                    return self.response_handler.handle_response(path, req)
+                
+                # programmatically setting type hint annotations for FastAPI's model validation 
+                endpoint.__annotations__ = {
+                    "req": models.request_envelope,
+                    "return": models.response_envelope
+                }
+                
+                return endpoint
+            
+            router.add_api_route(
+                path=path,
+                endpoint=create_endpoint(path),
+                methods=["POST"],
+                response_model_exclude_none=True
+            )
+    
+    def build_app(self):
+        """Builds FastAPI app."""
+        self.app = FastAPI(
+            title="KOI-net Protocol API",
+            version="1.1.0"
+        )
+        
+        self.app.add_exception_handler(ProtocolError, self.protocol_error_handler)
+        self.router = APIRouter(prefix="/koi-net")
+        self.build_endpoints(self.router)
+        self.app.include_router(self.router)
+        
+    def protocol_error_handler(self, request, exc: ProtocolError):
+        """Catches `ProtocolError` and returns an `ErrorResponse` payload."""
+        log.error(exc)
+        resp = ErrorResponse(error=EXCEPTION_TO_ERROR_TYPE[type(exc)])
+        log.info(f"Returning error response: {resp}")
+        return JSONResponse(
+            status_code=400,
+            content=resp.model_dump(mode="json")
+        )
+    
+    def run(self):
+        """Starts FastAPI server and event handler."""
+        
+        uvicorn.run(
+            app=self.app,
+            host=self.config.server.host,
+            port=self.config.server.port,
+            log_config=None
+        )