Protocols

Protocols define abstract interfaces (ports) used by applications and adapters. Providers implement these protocols for specific backends.

Supported Protocols

KeyValueStoreProtocol

The KeyValueStoreProtocol defines asynchronous operations for storing and retrieving values by key. It is generic over the value type V, which is determined by the concrete store implementation. Keys are ordinary str values, i.e. normal Unicode strings.

Its core operations are:

• get(key: str, default: V | None = None) -> V | None: Retrieve a value by key. Returns default (or None) when the key is not present.
• set(key: str, value: V) -> None: Store a value for a key.
• delete(key: str) -> None: Remove a key/value pair if present.
• exists(key: str) -> bool: Check whether a key exists.

The protocol is implemented by multiple provider families:

• in-memory testing providers: InMem*KeyValueStore
• Redis providers: Redis*KeyValueStore
• MongoDB providers: MongoDb*KeyValueStore
• S3 providers: S3*KeyValueStore
• Vault providers: Vault*KeyValueStore

Across these families, the same value-type variants are used:

• *BytesKeyValueStore: Stores raw bytes values.
• *StrKeyValueStore: Stores str values.
• *JsonKeyValueStore: Stores JSON objects.
• *DtoKeyValueStore: Stores Pydantic model instances (DTOs).

This naming convention is backend-agnostic, so switching provider families does not require changing your value model at the protocol level.

Choose the provider family based on the operational properties you need: in-memory for tests, Redis for fast access to small hot values, MongoDB for durable structured values, S3 for large or opaque payloads, and Vault for secrets or other sensitive values.

Choose the value-type variant based on how much structure and validation you want: Bytes for binary or already-serialized payloads, Str for plain text, Json for flexible schema-light objects, and Dto for schema-validated typed models.

Dao and DaoFactoryProtocol

The Dao protocol defines asynchronous CRUD and find operations on resources described by Pydantic models, and the DaoFactoryProtocol describes the factory that constructs DAOs, one per resource type. Together they let services persist and query data without depending on a specific database.

The protocol is implemented by the MongoDB provider for production use and by an in-memory mock DAO for unit testing.

These interfaces are documented in depth in the dedicated Data Access Objects chapter; for the architectural background, see The DAO Pattern.

DaoPublisher and DaoPublisherFactoryProtocol

The DaoPublisher protocol extends the Dao interface with automatic event publishing: every insert, update, or delete also emits a change event, implementing the publishing side of the outbox pattern. Instances are constructed by factories described by the DaoPublisherFactoryProtocol.

The protocol is implemented by the MongoDB + Kafka provider and documented in depth in the dedicated DAO Publisher chapter.

DaoSubscriberProtocol

The DaoSubscriberProtocol is the consuming counterpart of the DaoPublisher: a translator interface for services that mirror resources owned by another service by consuming its outbox events. Implementations declare the event topic and payload model and handle just two callbacks: changed() and deleted().

Translators implementing the protocol are run by the KafkaOutboxSubscriber provider and documented in depth in the dedicated DAO Subscriber chapter.

EventPublisherProtocol and EventSubscriberProtocol

The EventPublisherProtocol and EventSubscriberProtocol (from hexkit.protocols.eventpub and hexkit.protocols.eventsub) define the publishing and consuming of events through an event broker: publish() on the one side, and translator classes with topics and types of interest plus a consume() method on the other. They are the foundation of hexkit’s event-driven architecture support.

Both are implemented by the Apache Kafka provider; see the Kafka Event Publisher and Kafka Event Subscriber chapters, which also document the protocol usage itself.

ObjectStorageProtocol

The ObjectStorageProtocol defines asynchronous operations for S3-like object storage: managing buckets and file objects, and orchestrating uploads and downloads through presigned URLs, so that file content never flows through the service itself.

The protocol is implemented by the S3 provider, which works with any S3-compatible backend such as AWS S3, MinIO, or Ceph RGW.

This interface is documented in depth in the dedicated Object Storage chapter.

Adding Protocols

TBD