This document records current engineering choices. It is descriptive, not a promise that internal modules will never change.
One client-facing API
Choice: application code uses ExWapp with %ExWapp.Client{}.
Why: it keeps process topology, protocol workers, and storage details out of callers. The same API can use the built-in runtime, a controlled test double, or another complete adapter.
Cost: older PID-based Session functions remain visible during the migration period and can make the boundary look less strict than it is. They are internal compatibility entry points and do not carry the public compatibility promise.
Caller-owned client state
Choice: mutating public operations return an updated client instead of hiding all state behind a globally named process.
Why: applications can choose a GenServer, GenStateMachine, job, ETS table, or plain functional flow as the owner. Tests do not need a fixed runtime.
Cost: callers must retain the latest returned client. Using an older value can discard status, metadata, error, or trace updates.
Configurable JSON implementation
Choice: ExWapp has no runtime dependency on a specific JSON package. The
host configures config :ex_wapp, :json_library.
Why: JSON is an application-wide choice in many Elixir systems. Avoiding a forced implementation prevents dependency conflicts and lets hosts reuse the library already present in their release.
Cost: startup configuration is required. ExWapp.JSON validates missing
modules, unsupported APIs, invalid return shapes, and non-iodata encoders so
misconfiguration fails explicitly rather than corrupting persisted data.
Generated protobuf snapshot
Choice: generated Protox modules are checked in and updated as one snapshot.
Why: private protocol schemas drift. Deterministic generated sources make a release reproducible and allow reviews to see schema changes. Stale generated files are removed during regeneration.
Cost: the repository contains many generated modules. They must not be edited by hand, and conventional line coverage is meaningless if every schema module is counted as maintained application logic.
Per-key mutation serialization
Choice: Signal and app-state mutations that share a logical key are serialized, while unrelated keys can proceed concurrently.
Why: cryptographic ratchets and authenticated collection versions are state machines; concurrent updates to the same state can reuse or skip keys and make later messages undecipherable.
Cost: contention for one peer or collection is intentionally sequential. The current in-process lock coordinator has an unbounded waiter queue and does not persist ownership across a coordinator crash.
Durable send semantics
Choice: storage/flush failure remains a send error, and a transport write is distinguished from server acceptance or recipient delivery.
Why: retry receipts require the original message, identifier, and matching cryptographic state. Reporting success before those invariants hold gives the caller a result the runtime cannot reliably repair.
Cost: send calls can fail even when some work was already performed. Callers must use returned structured errors and asynchronous receipts rather than treat one return value as end-to-end delivery proof.
Bounded data queue and priority control path
Choice: ordinary outbound work is bounded, while immediate protocol ACKs use a priority lane.
Why: an overloaded application must exert backpressure instead of growing memory indefinitely. ACK starvation can cause the server to close an otherwise healthy stream.
Cost: the runtime can reject application sends under sustained pressure. Operators must observe queue and send-health telemetry and choose appropriate rate limits.
Adapter boundaries for stores and events
Choice: persistence and event delivery are behaviours.
Why: the library should not dictate a database, PubSub system, or process layout. Built-in adapters provide a usable default while production systems can integrate their existing infrastructure.
Cost: custom adapters own their durability, ordering, and operational quality. Passing behaviour tests is necessary but does not replace database and failure-mode testing in the host application.