Tighten marina error types to documented sum

Three correctness sweeps in one commit, no behaviour changes:

1. error/0 was {error, term()}, which gave dialyzer nothing. Replace
   with {error, error_reason()} where error_reason/0 enumerates:

   - marina_pool_not_started, timeout (marina-level)
   - cql_error() = {pos_integer(), binary()} (server-side CQL error)
   - no_server, pool_not_started, shackle_not_started (shackle)

   cql_error/0 exported so callers can match against it cleanly.

2. marina_body:decode/1 said it returned {error, atom()} but the
   actual return is {error, {Code, Msg}}. Spec was wrong; dialyzer
   silently accepted it because no caller destructured. Fixed to
   {error, cql_error()}.

3. Four marina_types specs were wrong about null handling:

   - decode_short_bytes/1 and decode_string/1 can return
     {null, binary()} on the 0xFFFF sentinel.
   - encode_bytes/1 and encode_short_bytes/1 accept null as input.

   The functions handled null correctly already -- the specs just
   lied about the contract.

Existing callers continue to work; dialyzer now catches {error, typo}
at call sites.

Author: lpgauth

CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.4.5
+
+### Changed
+
+- `error/0` is now `{error, error_reason()}` where `error_reason/0`
+  is a documented sum type — was `{error, term()}`, which gave
+  dialyzer nothing to check at call sites. The sum covers:
+
+  - `marina_pool_not_started` and `timeout` (marina-level)
+  - `cql_error()` — `{Code :: pos_integer(), Msg :: binary()}`, the
+    Cassandra/Scylla server-side error tuple
+  - `no_server`, `pool_not_started`, `shackle_not_started` (shackle
+    errors that propagate through marina)
+
+  `cql_error/0` is exported as a public type so callers can pattern-
+  match against it cleanly.
+
+- `marina_body:decode/1` spec corrected: was `{error, atom()}`,
+  is actually `{error, cql_error()}` — the `{Code, Msg}` shape was
+  documented but the spec contradicted it. Real bug; dialyzer
+  was silently accepting `atom()` because no caller was destructuring.
+
+- Four `marina_types` spec corrections (real correctness bugs, not
+  just imprecision):
+
+  - `decode_short_bytes/1` and `decode_string/1` can return
+    `{null, binary()}` on the 0xFFFF sentinel; specs claimed
+    `{binary(), binary()}`.
+  - `encode_bytes/1` and `encode_short_bytes/1` accept `null` as
+    input (encoded as the sentinel); specs claimed `binary()` only.
+
+  No behavioural change — the functions handled `null` correctly
+  already, the specs just lied about it.
+
+No source changes beyond the type tightening; existing callers
+continue to work unchanged. Dialyzer now flags `{error, typo}`
+at call sites that don't match the sum.
+
 ## 0.4.4
 
 ### Added

include/marina.hrl

@@ -64,7 +64,15 @@
 -type batch_query() ::
     {query, query(), values()} |
     {prepared, statement_id(), values()}.
--type error() :: {error, term()}.
+-type cql_error() :: {pos_integer(), binary()}.
+-type error_reason() ::
+    %% marina-level
+    marina_pool_not_started | timeout |
+    %% Cassandra/Scylla server-side error: {Code, Msg}
+    cql_error() |
+    %% shackle errors that propagate through marina
+    no_server | pool_not_started | shackle_not_started.
+-type error() :: {error, error_reason()}.
 -type frame() :: #frame {}.
 -type frame_flag() :: 0..1.
 -type query() :: binary().

src/marina.app.src

@@ -1,6 +1,6 @@
 {application, marina, [
   {description, "High-Performance Erlang Cassandra / Scylla CQL Client"},
-  {vsn, "0.4.4"},
+  {vsn, "0.4.5"},
   {registered, []},
   {applications, [
     kernel,

src/marina_body.erl

@@ -9,7 +9,7 @@
 ]).
 
 %% public
--spec decode(frame()) -> {ok, term()} | {error, atom()}.
+-spec decode(frame()) -> {ok, term()} | {error, cql_error()}.
 
 decode(#frame {flags = Flags, body = Body, opcode = Opcode}) ->
     Body1 = maybe_decompress(Flags, Body),

src/marina_types.erl

@@ -86,14 +86,14 @@ decode_number_list(<<Length:32, Rest/binary>>) ->
 decode_short(<<Value:16/signed, Rest/binary>>) ->
     {Value, Rest}.
 
--spec decode_short_bytes(binary()) -> {binary(), binary()}.
+-spec decode_short_bytes(binary()) -> {null | binary(), binary()}.
 
 decode_short_bytes(<<255, 255, Rest/binary>>) ->
     {null, Rest};
 decode_short_bytes(<<Pos:16, Value:Pos/binary, Rest/binary>>) ->
     {Value, Rest}.
 
--spec decode_string(binary()) -> {binary(), binary()}.
+-spec decode_string(binary()) -> {null | binary(), binary()}.
 
 decode_string(Bin) ->
     decode_short_bytes(Bin).
@@ -128,7 +128,7 @@ decode_uuid(<<Value:16/binary, Rest/binary>>) ->
 encode_boolean(false) -> <<0>>;
 encode_boolean(true) -> <<1>>.
 
--spec encode_bytes(binary()) -> binary().
+-spec encode_bytes(null | binary()) -> binary().
 
 encode_bytes(null) ->
     <<255, 255, 255, 255>>;
@@ -169,7 +169,7 @@ encode_long_string(Value) ->
 encode_short(Value) ->
     <<Value:16/signed>>.
 
--spec encode_short_bytes(binary()) -> binary().
+-spec encode_short_bytes(null | binary()) -> binary().
 
 encode_short_bytes(null) ->
     <<255, 255>>;