# Protocols

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


# Supported Protocols


## KeyValueStoreProtocol

The [`KeyValueStoreProtocol`](../../reference/protocols.kvstore.KeyValueStoreProtocol.md) 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`](../../user-guide/providers/testing.md)
- Redis providers: [`Redis*KeyValueStore`](../../user-guide/providers/redis.md)
- MongoDB providers: [`MongoDb*KeyValueStore`](../../user-guide/providers/mongodb.md#mongodb-kv-store-providers)
- S3 providers: [`S3*KeyValueStore`](../../user-guide/providers/s3.md#s3-kv-store-providers)
- Vault providers: [`Vault*KeyValueStore`](../../user-guide/providers/vault.md)

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`](../../reference/protocols.dao.Dao.md) protocol defines asynchronous CRUD and find operations on resources described by Pydantic models, and the [`DaoFactoryProtocol`](../../reference/protocols.dao.DaoFactoryProtocol.md) 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](../../user-guide/providers/mongodb.md#mongodb-dao) for production use and by an [in-memory mock DAO](../../user-guide/providers/testing.md) for unit testing.

These interfaces are documented in depth in the dedicated [Data Access Objects](../../user-guide/protocols/dao.md) chapter; for the architectural background, see [The DAO Pattern](../../user-guide/arch_concepts/dao_pattern.md).


## DaoPublisher and DaoPublisherFactoryProtocol

The [`DaoPublisher`](../../reference/protocols.daopub.DaoPublisher.md) protocol extends the [Dao](../../reference/protocols.dao.Dao.md#hexkit.protocols.dao.Dao) interface with automatic event publishing: every insert, update, or delete also emits a change event, implementing the publishing side of the [outbox pattern](../../user-guide/arch_concepts/event_driven_arch.md#outbox-pattern). Instances are constructed by factories described by the [`DaoPublisherFactoryProtocol`](../../reference/protocols.daopub.DaoPublisherFactoryProtocol.md).

The protocol is implemented by the [MongoDB + Kafka provider](../../user-guide/providers/mongokafka.md#outbox-publisher) and documented in depth in the dedicated [DAO Publisher](../../user-guide/protocols/daopublisher.md) chapter.


## DaoSubscriberProtocol

The [`DaoSubscriberProtocol`](../../reference/protocols.daosub.DaoSubscriberProtocol.md) is the consuming counterpart of the [DaoPublisher](../../reference/protocols.daopub.DaoPublisher.md#hexkit.protocols.daopub.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()](../../reference/protocols.daosub.DaoSubscriberProtocol.md#hexkit.protocols.daosub.DaoSubscriberProtocol.changed) and [deleted()](../../reference/protocols.daosub.DaoSubscriberProtocol.md#hexkit.protocols.daosub.DaoSubscriberProtocol.deleted).

Translators implementing the protocol are run by the [`KafkaOutboxSubscriber`](../../user-guide/providers/kafka/index.md) provider and documented in depth in the dedicated [DAO Subscriber](../../user-guide/protocols/daosubscriber.md) chapter.


## EventPublisherProtocol and EventSubscriberProtocol

The [`EventPublisherProtocol`](../../reference/protocols.eventpub.EventPublisherProtocol.md) and [`EventSubscriberProtocol`](../../reference/protocols.eventsub.EventSubscriberProtocol.md) (from `hexkit.protocols.eventpub` and `hexkit.protocols.eventsub`) define the publishing and consuming of events through an event broker: [publish()](../../reference/protocols.eventpub.EventPublisherProtocol.md#hexkit.protocols.eventpub.EventPublisherProtocol.publish) on the one side, and translator classes with topics and types of interest plus a [consume()](../../reference/protocols.eventsub.DLQSubscriberProtocol.md#hexkit.protocols.eventsub.DLQSubscriberProtocol.consume) method on the other. They are the foundation of hexkit's [event-driven architecture](../../user-guide/arch_concepts/event_driven_arch.md) support.

Both are implemented by the [Apache Kafka provider](../../user-guide/providers/kafka/index.md); see the [Kafka Event Publisher](../../user-guide/providers/kafka/publisher.md) and [Kafka Event Subscriber](../../user-guide/providers/kafka/subscriber.md) chapters, which also document the protocol usage itself.


## ObjectStorageProtocol

The [`ObjectStorageProtocol`](../../reference/protocols.objstorage.ObjectStorageProtocol.md) 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](../../user-guide/providers/s3.md#s3-object-storage-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](../../user-guide/protocols/objstorage.md) chapter.


# Adding Protocols

TBD