The choice of HIO for KERIpy was deliberate and based on three key alignment factors:

1. Asynchronous nature compliance - KERI's protocol design requires asynchronous event processing
2. Minimal sufficient means - HIO adheres to KERI's design philosophy of using the simplest adequate solution
3. Implementation efficiency - Provides necessary concurrency without unnecessary complexity

Key Features & Capabilities

Rich Flow-Based Programming

HIO implements Rich Flow Based Programming with Hierarchical Structured Concurrency. This programming paradigm defines applications as networks of processes where:

• Data flows through connected processing components
• Each component performs specific transformations
• Components can be composed hierarchically
• Execution is managed through structured lifecycle contexts

This approach is particularly well-suited for KERI's event-driven architecture where key events flow through validation pipelines, witness networks, and watcher services.

Hierarchical Structured Concurrency

The hierarchical aspect of HIO provides:

• Parent-child relationships between concurrent operations
• Lifecycle management where parent operations control child operation lifetimes
• Error propagation up the hierarchy for proper exception handling
• Resource cleanup guaranteed through structured teardown

This structure prevents common async programming pitfalls like:

• Orphaned tasks that continue running after their parent completes
• Resource leaks from improperly cancelled operations
• Race conditions from uncoordinated concurrent access

Weightless Coroutines

HIO's coroutines are described as weightless, meaning:

• Minimal memory overhead per coroutine instance
• Efficient context switching between concurrent operations
• Scalable to thousands of concurrent operations
• No thread overhead - pure async/await based concurrency

This efficiency is critical for KERI implementations that may need to:

• Manage hundreds of AIDs simultaneously
• Process thousands of events per second
• Maintain connections to multiple witnesses and watchers
• Handle concurrent credential issuance requests

Asynchronous I/O Operations

HIO provides non-blocking I/O primitives for:

• Network communication - TCP/HTTP connections to witnesses, watchers, and agents
• File operations - Reading/writing KELs, KERLs, and credential stores
• Database access - Async queries to identifier and event databases
• Stream processing - Handling CESR encoded event streams

All I/O operations are designed to never block the event loop, ensuring responsive systems even under high load.

Doer Pattern and Architecture

HIO introduces the Doer pattern as its primary abstraction for concurrent operations. According to the KERIpy/HIO Style Guide, there are two main patterns for working with Doers:

Pattern 1: doing.doify Wrapper

This pattern wraps methods that construct and hand off coroutines to parent Doers:

class MigrateDoDoer(doing.DoDoer):
    def __init__(self, agency, **kwa):
        super(MigrateDoDoer, self).__init__(doers=self.migrateAgentsDo(), **kwa)
        self.agency = agency

    @doing.doify
    def migrateAgentsDo(self):
        for agent in self.agency.agents:
            doer = MigrateDoer(agent=agent)
            self.extend([doer])
            yield

In this pattern:

• The @doing.doify decorator converts the method into a generator
• The method constructs Doer instances for each agent
• Constructed Doers are handed to the parent DoDoer via self.extend()
• The yield statement is syntactically required but not functionally necessary

Pattern 2: .recur() Override

A simpler approach that directly overrides the .recur() method:

class MigrateDoDoer(doing.DoDoer):
    def __init__(self, agency, **kwa):
        super(MigrateDoDoer, self).__init__(**kwa)
        self.agency = agency

    def recur(self, tyme):
        self.migrateAgentsDo()
        return super().recur(tyme=tyme)

    def migrateAgentsDo(self):
        for agent in self.agency.agents:
            doer = MigrateDoer(agent=agent)
            self.extend([doer])

This pattern:

• Eliminates the @doing.doify wrapper
• Removes unnecessary yield statements
• Makes the code more straightforward
• Requires calling super().recur() to maintain normal DoDoer execution

Key Technical Consideration: When implementing a custom .recur() function in a DoDoer subclass, the superclass .recur() must be called to resume normal DoDoer execution of all contained coroutines.

Cues for Inter-Component Communication

While not fully documented in the provided sources, the style guide indicates that HIO includes a Cues system for inter-component communication. This appears to be a planned or emerging pattern for coordinating between different parts of a KERI implementation.

Installation & Setup

Based on the Trinity requirements.txt, HIO is installed as a standard Python package:

pip install hio>=0.6.12

Dependencies

HIO has minimal dependencies, aligning with its "weightless" design philosophy. The library builds upon:

• Python's native asyncio framework
• Standard library async primitives

For KERI implementations, HIO is typically installed alongside:

• keri>=1.2.0-dev1 - Core KERI protocol implementation
• multicommand>=1.0.0 - CLI utilities
• dataclasses_json>=0.5.7 - JSON serialization support

Basic Configuration

HIO does not require explicit configuration files. Instead, it is used programmatically within Python applications. The hierarchical structure is established through code organization rather than external configuration.

Usage & API

Core Abstractions

While detailed API documentation is not provided in the source documents, the key abstractions mentioned include:

Doers and DoDoers

• Doer: Base class for concurrent operations
• DoDoer: Container Doer that manages child Doers
• Lifecycle methods: .recur() for periodic execution

Generator Mechanics

The style guide emphasizes understanding when generator mechanics (yield, yield from) are genuinely needed versus when they're syntactically present but functionally unnecessary. This distinction is important for:

• Choosing between doing.doify and .recur() override patterns
• Understanding execution flow in hierarchical coroutines
• Optimizing performance by avoiding unnecessary generator overhead

Common Usage Patterns

Based on the KERIA architecture description, HIO is used for:

Asynchronous Message Routing

The Message Router in KERIA uses HIO to handle:

• Asynchronous waiting for multi-signature responses
• Routing incoming protocol messages to appropriate agents
• Managing concurrent connections from multiple KERI clients

Agent Provisioning

The Agency component uses HIO for:

• Processing /boot requests to provision new agents
• Managing agent lifecycle and persistence
• Coordinating between multiple agent instances

API Request Processing

The API Handler leverages HIO to:

• Process concurrent API requests from Signify clients
• Manage agent-specific database interactions
• Handle signature verification in request headers

Event Processing

Individual Agents use HIO for:

• Processing key events asynchronously
• Coordinating with witnesses and watchers
• Managing credential issuance and verification workflows

Related Implementations

Historical Foundation: ioflo

HIO builds upon very early work on hierarchical structured concurrency with lifecycle contexts from ioflo:

• ioflo framework
• ioflo GitHub repository
• ioflo manuals

The ioflo project pioneered:

• Hierarchical structured concurrency patterns
• Lifecycle context management
• Flow-based programming paradigms

HIO represents an evolution and refinement of these concepts specifically optimized for KERI's requirements.

KERI Ecosystem Integration

HIO is the standard async infrastructure for Python-based KERI implementations:

KERIpy

The reference Python implementation of KERI uses HIO for:

• Event processing pipelines
• Witness and watcher communication
• KEL and KERL management

KERIA

The cloud agent service uses HIO for:

• Multi-tenant agent management
• Concurrent API request handling
• Asynchronous message routing

SignifyPy

The Python client library uses HIO for:

• Non-blocking API calls to KERIA
• Concurrent credential operations
• Event stream processing

Alternative Approaches in Other Languages

Other KERI implementations use different async frameworks:

• SignifyTS (TypeScript) - Uses JavaScript's native async/await with Node.js event loop
• KERI-Ox (Rust) - Uses Tokio async runtime
• CESRide (Rust) - Uses Rust's async ecosystem

Each implementation adapts the hierarchical structured concurrency concepts to the idioms and capabilities of its target language.

Implementation Notes

Design Philosophy Alignment

The selection of HIO for KERIpy reflects KERI's core design principles:

1. Minimal Sufficient Means: HIO provides exactly what's needed for async operations without unnecessary features or complexity
2. Asynchronous Nature: KERI's event-driven protocol requires non-blocking I/O and concurrent processing
3. Hierarchical Organization: KERI's layered architecture (identifiers → witnesses → watchers → agents) maps naturally to HIO's hierarchical structure

When to Use Each Pattern

According to the style guide:

Use doing.doify when:

• You need sub-generator functionality with actual suspension points
• The method performs complex async operations that require yielding control
• You're working with existing code that uses this pattern

Use .recur() override when:

• You're simply constructing and handing off Doers to a parent
• No actual suspension/resumption is needed
• You want cleaner, more straightforward code

Performance Considerations

HIO's "weightless" design means:

• Thousands of concurrent operations are feasible on modest hardware
• Memory overhead is minimal compared to thread-based concurrency
• Context switching is efficient through Python's async/await
• I/O operations never block the event loop

This efficiency is critical for KERI implementations that may need to:

• Manage large numbers of AIDs
• Process high-volume event streams
• Maintain many concurrent network connections
• Handle burst loads during credential issuance

Error Handling and Lifecycle Management

The hierarchical structure ensures:

• Proper cleanup when operations complete or fail
• Error propagation up the hierarchy for centralized handling
• Resource management through structured teardown
• Graceful degradation when components fail

This is particularly important for long-running KERI services like KERIA agents that must maintain reliability over extended periods.

Integration with KERI Event Processing

HIO's flow-based programming model aligns naturally with KERI's event processing:

1. Events flow through validation pipelines
2. Witnesses process events concurrently
3. Watchers observe event streams asynchronously
4. Agents coordinate multiple concurrent operations

Each stage can be implemented as a Doer or DoDoer, creating a clean hierarchical structure that mirrors the protocol's logical organization.

Future Development

The style guide indicates planned documentation for:

• Cues for inter-component communication - A mechanism for coordinating between different parts of a KERI implementation
• Additional idiomatic patterns for common KERI operations
• Performance optimization techniques for high-load scenarios

These additions will further enhance HIO's utility as the foundational async infrastructure for the KERI ecosystem.

Stay updated with the KERIpy style guide for evolving best practices.