koi-net 1.1.0b1__tar.gz → 1.1.0b2__tar.gz

{koi_net-1.1.0b1 → koi_net-1.1.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: koi-net
-Version: 1.1.0b1
+Version: 1.1.0b2
 Summary: Implementation of KOI-net protocol in Python
 Project-URL: Homepage, https://github.com/BlockScience/koi-net/
 Author-email: Luke Miller <luke@block.science>
@@ -28,19 +28,19 @@ License: MIT License
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: cryptography>=45.0.3
+Requires-Dist: fastapi>=0.115.12
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: networkx>=3.4.2
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rid-lib>=3.2.7
 Requires-Dist: ruamel-yaml>=0.18.10
+Requires-Dist: uvicorn>=0.34.2
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: twine>=6.0; extra == 'dev'
 Provides-Extra: examples
-Requires-Dist: fastapi; extra == 'examples'
 Requires-Dist: rich; extra == 'examples'
-Requires-Dist: uvicorn; extra == 'examples'
 Description-Content-Type: text/markdown
 
 # KOI-net

koi_net-1.1.0b2/examples/coordinator.py

@@ -0,0 +1,76 @@
+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
+from koi_net.protocol.node import NodeProfile, NodeProvides, NodeType
+from koi_net import NodeInterface
+from koi_net.context import HandlerContext
+from koi_net.processor.handler import HandlerType
+from koi_net.processor.knowledge_object import KnowledgeObject
+from koi_net.protocol.event import Event, EventType
+from koi_net.protocol.edge import EdgeType, generate_edge_bundle
+
+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 CoordinatorConfig(NodeConfig):
+    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]
+                )
+            ),
+            cache_directory_path=".coordinator_rid_cache",
+            event_queues_path="coordinator_event_queues.json",
+            private_key_pem_path="coordinator_priv_key.pem"
+        )
+    )
+    
+node = NodeInterface(
+    config=CoordinatorConfig.load_from_yaml("coordinator_config.yaml"),
+    use_kobj_processor_thread=True
+)
+
+@node.processor.pipeline.register_handler(HandlerType.Network, rid_types=[KoiNetNode])
+def handshake_handler(ctx: HandlerContext, kobj: KnowledgeObject):
+    logger.info("Handling node handshake")
+
+    # only respond if node declares itself as NEW
+    if kobj.event_type != EventType.NEW:
+        return
+        
+    logger.info("Sharing this node's bundle with peer")
+    identity_bundle = ctx.effector.deref(ctx.identity.rid)
+    ctx.event_queue.push_event_to(
+        event=Event.from_bundle(EventType.NEW, identity_bundle),
+        node=kobj.rid,
+        flush=True
+    )
+    
+    logger.info("Proposing new edge")    
+    # defer handling of proposed edge
+    
+    edge_bundle = generate_edge_bundle(
+        source=kobj.rid,
+        target=ctx.identity.rid,
+        edge_type=EdgeType.WEBHOOK,
+        rid_types=[KoiNetNode, KoiNetEdge]
+    )
+        
+    ctx.handle(rid=edge_bundle.rid, event_type=EventType.FORGET)
+    ctx.handle(bundle=edge_bundle)
+    
+if __name__ == "__main__":
+    node.server.run()

koi_net-1.1.0b1/examples/basic_partial_node.py → koi_net-1.1.0b2/examples/partial.py

@@ -1,10 +1,9 @@
-import time
 import logging
 from pydantic import Field
 from rich.logging import RichHandler
 from koi_net import NodeInterface
 from koi_net.protocol.node import NodeProfile, NodeType
-from koi_net.config import NodeConfig, KoiNetConfig, NodeContact
+from koi_net.config import NodeConfig, KoiNetConfig
 
 logging.basicConfig(
     level=logging.INFO,
@@ -24,25 +23,15 @@ class PartialNodeConfig(NodeConfig):
             node_profile=NodeProfile(
                 node_type=NodeType.PARTIAL
             ),
-            cache_directory_path=".basic_partial_rid_cache",
-            event_queues_path="basic_partial_event_queues.json"
+            cache_directory_path=".partial_rid_cache",
+            event_queues_path="partial_event_queues.json",
+            private_key_pem_path="partial_priv_key.pem"
         )
     )
 
-
 node = NodeInterface(
-    config=PartialNodeConfig.load_from_yaml("basic_partial_config.yaml")
+    config=PartialNodeConfig.load_from_yaml("partial_config.yaml")
 )
 
-
-node.start()
-
-while True:
-    neighbors = node.resolver.poll_neighbors()
-    for node_rid in neighbors:
-        events = neighbors[node_rid]
-        for event in events:
-            node.processor.handle(event=event, source=node_rid)
-    node.processor.flush_kobj_queue()
-    
-    time.sleep(5)
+if __name__ == "__main__":
+    node.poller.run()

{koi_net-1.1.0b1 → koi_net-1.1.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "koi-net"
-version = "1.1.0-beta.1"
+version = "1.1.0-beta.2"
 description = "Implementation of KOI-net protocol in Python"
 authors = [
     {name = "Luke Miller", email = "luke@block.science"}
@@ -19,15 +19,15 @@ dependencies = [
     "pydantic>=2.10.6",
     "ruamel.yaml>=0.18.10",
     "python-dotenv>=1.1.0",
-    "cryptography>=45.0.3"
+    "cryptography>=45.0.3",
+    "fastapi>=0.115.12",
+    "uvicorn>=0.34.2"
 ]
 
 [project.optional-dependencies]
 dev = ["twine>=6.0", "build"]
 examples = [
     "rich",
-    "fastapi",
-    "uvicorn"
 ]
 
 [project.urls]

{koi_net-1.1.0b1 → koi_net-1.1.0b2}/src/koi_net/config.py

@@ -29,6 +29,7 @@ class KoiNetConfig(BaseModel):
     cache_directory_path: str = ".rid_cache"
     event_queues_path: str = "event_queues.json"
     private_key_pem_path: str = "priv_key.pem"
+    polling_interval: int = 5
     
     first_contact: NodeContact = Field(default_factory=NodeContact)
     

{koi_net-1.1.0b1 → koi_net-1.1.0b2}/src/koi_net/core.py

@@ -1,5 +1,5 @@
 import logging
-import httpx
+from koi_net.protocol.node import NodeType
 from rid_lib.ext import Cache
 from .network.resolver import NetworkResolver
 from .network.event_queue import NetworkEventQueue
@@ -17,6 +17,9 @@ from .secure import Secure
 from .config import NodeConfig
 from .context import HandlerContext, ActionContext
 from .effector import Effector
+from .server import NodeServer
+from .lifecycle import NodeLifecycle
+from .poller import NodePoller
 from . import default_actions
 
 logger = logging.getLogger(__name__)
@@ -32,16 +35,15 @@ class NodeInterface:
     graph: NetworkGraph
     processor: ProcessorInterface
     secure: Secure
+    server: NodeServer
     
     use_kobj_processor_thread: bool
     
     def __init__(
-        self, 
+        self,
         config: NodeConfig,
         use_kobj_processor_thread: bool = False,
-        
         handlers: list[KnowledgeHandler] | None = None,
-        
         cache: Cache | None = None,
         processor: ProcessorInterface | None = None
     ):
@@ -49,9 +51,8 @@ class NodeInterface:
         self.cache = cache or Cache(
             directory_path=self.config.koi_net.cache_directory_path
         )
-        
+
         self.identity = NodeIdentity(config=self.config)
-        
         self.effector = Effector(cache=self.cache)
 
         self.graph = NetworkGraph(
@@ -146,47 +147,30 @@ class NodeInterface:
         self.effector.set_processor(self.processor)
         self.effector.set_resolver(self.resolver)
         self.effector.set_action_context(self.action_context)
-         
-            
-    def start(self) -> None:
-        """Starts a node, call this method first.
-        
-        Starts the processor thread (if enabled). Loads event queues into memory. Generates network graph from nodes and edges in cache. Processes any state changes of node bundle. Initiates handshake with first contact (if provided) if node doesn't have any neighbors.
-        """
-        if self.use_kobj_processor_thread:
-            logger.info("Starting processor worker thread")
-            self.processor.worker_thread.start()
-        
-        # self.network._load_event_queues()
-        self.graph.generate()
-        
-        # refresh to reflect changes (if any) in config.yaml
-        self.effector.deref(self.identity.rid, refresh_cache=True)
-                
-        logger.debug("Waiting for kobj queue to empty")
-        if self.use_kobj_processor_thread:
-            self.processor.kobj_queue.join()
-        else:
-            self.processor.flush_kobj_queue()
-        logger.debug("Done")
-    
-        if not self.graph.get_neighbors() and self.config.koi_net.first_contact.rid:
-            logger.debug(f"I don't have any neighbors, reaching out to first contact {self.config.koi_net.first_contact.rid!r}")
-            
-            self.actor.handshake_with(self.config.koi_net.first_contact.rid)
-            
-                        
-    def stop(self):
-        """Stops a node, call this method last.
-        
-        Finishes processing knowledge object queue. Saves event queues to storage.
-        """
-        logger.info("Stopping node...")
-        
-        if self.use_kobj_processor_thread:
-            logger.info(f"Waiting for kobj queue to empty ({self.processor.kobj_queue.unfinished_tasks} tasks remaining)")
-            self.processor.kobj_queue.join()
-        else:
-            self.processor.flush_kobj_queue()
-        
-        # self.network._save_event_queues()
+        
+        self.lifecycle = NodeLifecycle(
+            config=self.config,
+            identity=self.identity,
+            graph=self.graph,
+            processor=self.processor,
+            effector=self.effector,
+            actor=self.actor,
+            use_kobj_processor_thread=use_kobj_processor_thread
+        )
+        
+        # if self.config.koi_net.node_profile.node_type == NodeType.FULL:
+        self.server = NodeServer(
+            config=self.config,
+            lifecycle=self.lifecycle,
+            secure=self.secure,
+            processor=self.processor,
+            event_queue=self.event_queue,
+            response_handler=self.response_handler
+        )
+        
+        self.poller = NodePoller(
+            processor=self.processor,
+            lifecycle=self.lifecycle,
+            resolver=self.resolver,
+            config=self.config
+        )

koi_net-1.1.0b2/src/koi_net/lifecycle.py

@@ -0,0 +1,76 @@
+import logging
+
+from .network.behavior import Actor
+from .effector import Effector
+from .config import NodeConfig
+from .processor.interface import ProcessorInterface
+from .network.graph import NetworkGraph
+from .identity import NodeIdentity
+
+logger = logging.getLogger(__name__)
+
+
+class NodeLifecycle:
+    config: NodeConfig
+    graph: NetworkGraph
+    processor: ProcessorInterface
+    effector: Effector
+    actor: Actor
+    
+    def __init__(
+        self,
+        config: NodeConfig,
+        identity: NodeIdentity,
+        graph: NetworkGraph,
+        processor: ProcessorInterface,
+        effector: Effector,
+        actor: Actor,
+        use_kobj_processor_thread: bool
+    ):
+        self.config = config
+        self.identity = identity
+        self.graph = graph
+        self.processor = processor
+        self.effector = effector
+        self.actor = actor
+        self.use_kobj_processor_thread = use_kobj_processor_thread
+    
+    def start(self) -> None:
+        """Starts a node, call this method first.
+        
+        Starts the processor thread (if enabled). Loads event queues into memory. Generates network graph from nodes and edges in cache. Processes any state changes of node bundle. Initiates handshake with first contact (if provided) if node doesn't have any neighbors.
+        """
+        if self.use_kobj_processor_thread:
+            logger.info("Starting processor worker thread")
+            self.processor.worker_thread.start()
+        
+        self.graph.generate()
+        
+        # refresh to reflect changes (if any) in config.yaml
+        self.effector.deref(self.identity.rid, refresh_cache=True)
+                
+        logger.debug("Waiting for kobj queue to empty")
+        if self.use_kobj_processor_thread:
+            self.processor.kobj_queue.join()
+        else:
+            self.processor.flush_kobj_queue()
+        logger.debug("Done")
+    
+        if not self.graph.get_neighbors() and self.config.koi_net.first_contact.rid:
+            logger.debug(f"I don't have any neighbors, reaching out to first contact {self.config.koi_net.first_contact.rid!r}")
+            
+            self.actor.handshake_with(self.config.koi_net.first_contact.rid)
+            
+                        
+    def stop(self):
+        """Stops a node, call this method last.
+        
+        Finishes processing knowledge object queue. Saves event queues to storage.
+        """
+        logger.info("Stopping node...")
+        
+        if self.use_kobj_processor_thread:
+            logger.info(f"Waiting for kobj queue to empty ({self.processor.kobj_queue.unfinished_tasks} tasks remaining)")
+            self.processor.kobj_queue.join()
+        else:
+            self.processor.flush_kobj_queue()

koi_net-1.1.0b2/src/koi_net/poller.py

@@ -0,0 +1,45 @@
+
+import time
+import logging
+from .processor.interface import ProcessorInterface
+from .lifecycle import NodeLifecycle
+from .network.resolver import NetworkResolver
+from .config import NodeConfig
+
+logger = logging.getLogger(__name__)
+
+
+class NodePoller:
+    def __init__(
+        self,
+        processor: ProcessorInterface,
+        lifecycle: NodeLifecycle,
+        resolver: NetworkResolver,
+        config: NodeConfig
+    ):
+        self.processor = processor
+        self.lifecycle = lifecycle
+        self.resolver = resolver
+        self.config = config
+
+    def run(self):
+        try:
+            self.lifecycle.start()
+            while True:
+                start_time = time.time()
+                neighbors = self.resolver.poll_neighbors()
+                for node_rid in neighbors:
+                    for event in neighbors[node_rid]:
+                        self.processor.handle(event=event, source=node_rid)
+                self.processor.flush_kobj_queue()
+                
+                elapsed = time.time() - start_time
+                sleep_time = self.config.koi_net.polling_interval - elapsed
+                if sleep_time > 0:
+                    time.sleep(sleep_time)
+                    
+        except KeyboardInterrupt:
+            logger.info("Polling interrupted by user.")
+            
+        finally:
+            self.lifecycle.stop()

koi_net-1.1.0b2/src/koi_net/server.py

@@ -0,0 +1,128 @@
+import logging
+import uvicorn
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, APIRouter
+from fastapi.responses import JSONResponse
+from .network.event_queue import NetworkEventQueue
+from .network.response_handler import ResponseHandler
+from .processor.interface import ProcessorInterface
+from .protocol.api_models import (
+    PollEvents,
+    FetchRids,
+    FetchManifests,
+    FetchBundles,
+    EventsPayload,
+    RidsPayload,
+    ManifestsPayload,
+    BundlesPayload,
+    ErrorResponse
+)
+from .protocol.errors import ProtocolError
+from .protocol.envelope import SignedEnvelope
+from .protocol.consts import (
+    BROADCAST_EVENTS_PATH,
+    POLL_EVENTS_PATH,
+    FETCH_RIDS_PATH,
+    FETCH_MANIFESTS_PATH,
+    FETCH_BUNDLES_PATH
+)
+from .secure import Secure
+from .lifecycle import NodeLifecycle
+from .config import NodeConfig
+
+logger = logging.getLogger(__name__)
+
+
+class NodeServer:
+    lifecycle: NodeLifecycle
+    
+    def __init__(
+        self,
+        config: NodeConfig,
+        lifecycle: NodeLifecycle,
+        secure: Secure,
+        processor: ProcessorInterface,
+        event_queue: NetworkEventQueue,
+        response_handler: ResponseHandler
+    ):
+        self.config = config
+        self.lifecycle = lifecycle
+        self.secure = secure
+        self.processor = processor
+        self.event_queue = event_queue
+        self.response_handler = response_handler
+        self._build_app()
+        
+    def _build_app(self):
+        self.app = FastAPI(
+            lifespan=self.lifespan, 
+            title="KOI-net Protocol API",
+            version="1.0.0"
+        )
+        
+        self.router = APIRouter(prefix="/koi-net")
+        self.app.add_exception_handler(ProtocolError, self.protocol_error_handler)
+        
+        def _add_endpoint(path, func):
+            self.router.add_api_route(
+                path=path,
+                endpoint=self.secure.envelope_handler(func),
+                methods=["POST"]
+            )
+        
+        _add_endpoint(BROADCAST_EVENTS_PATH, self.broadcast_events)
+        _add_endpoint(POLL_EVENTS_PATH, self.poll_events)
+        _add_endpoint(FETCH_RIDS_PATH, self.fetch_rids)
+        _add_endpoint(FETCH_MANIFESTS_PATH, self.fetch_manifests)
+        _add_endpoint(FETCH_BUNDLES_PATH, self.fetch_bundles)
+        
+        self.app.include_router(self.router)
+    
+    def run(self):
+        uvicorn.run(
+            app=self.app,
+            host=self.config.server.host,
+            port=self.config.server.port
+        )
+        
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI):
+        self.lifecycle.start()
+        yield
+        self.lifecycle.stop()
+
+    def protocol_error_handler(self, request, exc: ProtocolError):
+        logger.info(f"caught protocol error: {exc}")
+        resp = ErrorResponse(error=exc.error_type)
+        logger.info(f"returning error response: {resp}")
+        return JSONResponse(
+            status_code=400,
+            content=resp.model_dump(mode="json")
+        )
+
+    async def broadcast_events(self, req: SignedEnvelope[EventsPayload]):
+        logger.info(f"Request to {BROADCAST_EVENTS_PATH}, received {len(req.payload.events)} event(s)")
+        for event in req.payload.events:
+            self.processor.handle(event=event, source=req.source_node)
+        
+    async def poll_events(
+        self, req: SignedEnvelope[PollEvents]
+    ) -> SignedEnvelope[EventsPayload] | ErrorResponse:
+        logger.info(f"Request to {POLL_EVENTS_PATH}")
+        events = self.event_queue.flush_poll_queue(req.payload.rid)
+        return EventsPayload(events=events)
+
+    async def fetch_rids(
+        self, req: SignedEnvelope[FetchRids]
+    ) -> SignedEnvelope[RidsPayload] | ErrorResponse:
+        return self.response_handler.fetch_rids(req.payload)
+
+    async def fetch_manifests(
+        self, req: SignedEnvelope[FetchManifests]
+    ) -> SignedEnvelope[ManifestsPayload] | ErrorResponse:
+        return self.response_handler.fetch_manifests(req.payload)
+
+    async def fetch_bundles(
+        self, req: SignedEnvelope[FetchBundles]
+    ) -> SignedEnvelope[BundlesPayload] | ErrorResponse:
+        return self.response_handler.fetch_bundles(req.payload)

koi_net-1.1.0b1/examples/basic_coordinator_node.py

@@ -1,111 +0,0 @@
-import json
-import logging
-from pydantic import Field
-import uvicorn
-from contextlib import asynccontextmanager
-from rich.logging import RichHandler
-from fastapi import FastAPI
-from rid_lib.types import KoiNetNode, KoiNetEdge
-from koi_net import NodeInterface
-from koi_net.config import NodeConfig, KoiNetConfig
-from koi_net.protocol.node import NodeProfile, NodeType, NodeProvides
-from koi_net.protocol.api_models import (
-    PollEvents,
-    FetchRids,
-    FetchManifests,
-    FetchBundles,
-    EventsPayload,
-    RidsPayload,
-    ManifestsPayload,
-    BundlesPayload
-)
-from koi_net.protocol.consts import (
-    BROADCAST_EVENTS_PATH,
-    POLL_EVENTS_PATH,
-    FETCH_RIDS_PATH,
-    FETCH_MANIFESTS_PATH,
-    FETCH_BUNDLES_PATH
-)
-
-
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-    datefmt="%Y-%m-%d %H:%M:%S",
-    handlers=[RichHandler()]
-)
-
-# TODO: UPDATE OR REMOVE, THIS EXAMPLE IS OUT OF DATE
-
-logging.getLogger("koi_net").setLevel(logging.DEBUG)
-
-
-class CoordinatorNodeConfig(NodeConfig):
-    koi_net: KoiNetConfig | None = Field(default_factory = lambda:
-        KoiNetConfig(
-            node_name="coordinator",
-            node_profile=NodeProfile(
-                node_type=NodeType.FULL,
-                provides=NodeProvides(
-                    event=[KoiNetNode, KoiNetEdge],
-                    state=[KoiNetNode, KoiNetEdge]
-                )
-            ),
-            cache_directory_path=".coordinator_rid_cache",
-            event_queues_path="coordinator_event_queues.json"
-        )
-    )
-
-node = NodeInterface(
-    config=CoordinatorNodeConfig.load_from_yaml("coordinator_config.yaml"),
-    use_kobj_processor_thread=True
-)
-
-
-logger = logging.getLogger(__name__)
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    node.start()
-    yield
-    node.stop()
-
-app = FastAPI(
-    lifespan=lifespan, 
-    root_path="/koi-net",
-    title="KOI-net Protocol API",
-    version="1.0.0"
-)
-
-@app.post(BROADCAST_EVENTS_PATH)
-def broadcast_events(req: EventsPayload):
-    logger.info(f"Request to {BROADCAST_EVENTS_PATH}, received {len(req.events)} event(s)")
-    for event in req.events:
-        node.processor.handle(event=event, source=KnowledgeSource.External)
-    
-@app.post(POLL_EVENTS_PATH)
-def poll_events(req: PollEvents) -> EventsPayload:
-    logger.info(f"Request to {POLL_EVENTS_PATH}")
-    events = node.event_queue.flush_poll_queue(req.rid)
-    return EventsPayload(events=events)
-
-@app.post(FETCH_RIDS_PATH)
-def fetch_rids(req: FetchRids) -> RidsPayload:
-    return node.response_handler.fetch_rids(req)
-
-@app.post(FETCH_MANIFESTS_PATH)
-def fetch_manifests(req: FetchManifests) -> ManifestsPayload:
-    return node.response_handler.fetch_manifests(req)
-
-@app.post(FETCH_BUNDLES_PATH)
-def fetch_bundles(req: FetchBundles) -> BundlesPayload:
-    return node.response_handler.fetch_bundles(req)
-    
-if __name__ == "__main__":
-    openapi_spec = app.openapi()
-
-    with open("koi-net-protocol-openapi.json", "w") as f:
-        json.dump(openapi_spec, f, indent=2)
-    
-    uvicorn.run("examples.basic_coordinator_node:app", port=node.config.server.port)