Append.hs

module Kiroku.Store.Append (
    appendToStream,
    appendMultiStream,
) where

import Effectful (Eff, (:>))
import Effectful.Dispatch.Dynamic (send)
import GHC.Stack (HasCallStack)
import Kiroku.Store.Effect (Store (..))
import Kiroku.Store.Types

{- | Append a batch of events to a single stream under the given
'ExpectedVersion' precondition.

When to use this vs.
'Kiroku.Store.Transaction.runTransactionAppending':

* Reach for 'appendToStream' by default. It is the cheapest path —
  one CTE on a pool connection, no Haskell-layer @BEGIN@/@COMMIT@
  envelope, no caller-driven retry semantics to reason about.
* Reach for 'Kiroku.Store.Transaction.runTransactionAppending' /only/
  when you need to atomically combine the append with additional SQL
  writes that the store doesn't perform (most prominently a
  projection-row insert from a downstream projection table). The
  wrapper opens an explicit 'BEGIN'/'COMMIT', enables PostgreSQL
  serialization-conflict retry of the entire body by default, and
  threads the caller's continuation into the same transaction.

Semantics:

* If the precondition fails, the entire batch is rejected — appends are
  all-or-nothing per call.
* On success, events are visible to subsequent reads on /this/ store
  handle (read-your-own-writes is guaranteed). Other store handles see
  the events after their pool connection's transaction-visibility
  horizon advances.
* The returned 'AppendResult' carries the position of the /last/ event
  in the batch.

Idempotent retries: supply 'Kiroku.Store.Types.EventData.eventId' yourself
and retry on transient failures. A retry whose previous attempt actually
committed surfaces as 'Kiroku.Store.Error.DuplicateEvent' (when the
events_pkey detail is parseable). A retry that observed
'Kiroku.Store.Error.WrongExpectedVersion' on an 'ExactVersion' append
should be treated as ambiguous: either a concurrent writer raced you or
your previous attempt succeeded; the recovery in both cases is to
re-read the stream and decide.

Errors (all variants of 'Kiroku.Store.Error.StoreError'):

* 'Kiroku.Store.Error.WrongExpectedVersion' — 'ExactVersion' mismatch.
* 'Kiroku.Store.Error.StreamNotFound' — 'StreamExists' against a missing
  or soft-deleted stream.
* 'Kiroku.Store.Error.ReservedStreamName' — the target is @$all@, which
  is the global read stream and cannot be appended as an application
  stream.
* 'Kiroku.Store.Error.StreamAlreadyExists' — 'NoStream' against an
  existing stream (including soft-deleted).
* 'Kiroku.Store.Error.DuplicateEvent' — caller-supplied 'eventId'
  collides with an existing event.
* 'Kiroku.Store.Error.EmptyAppendBatch' — the supplied event list is
  empty.

Empty event lists: passing @[]@ is a programming mistake. The
interpreter rejects the call with 'Kiroku.Store.Error.EmptyAppendBatch'
before any database work. This avoids taking the global @$all@ row lock,
firing notifications, or creating an empty stream under 'NoStream'.
-}
appendToStream ::
    (HasCallStack, Store :> es) =>
    StreamName ->
    ExpectedVersion ->
    [EventData] ->
    Eff es AppendResult
appendToStream name expected events = send (AppendToStream name expected events)

{- | Atomically append events to multiple streams in a single
transaction.

Either every per-stream append succeeds or all of them roll back —
there is no partial-commit state. The interpreter pre-locks the named
streams in deterministic @stream_id@ order to avoid deadlocks when two
concurrent multi-stream calls touch overlapping streams in different
user orders.

@$all@ is reserved for the global read stream. If any operation targets
@$all@, the whole call is rejected before opening the transaction with
'Kiroku.Store.Error.ReservedStreamName'.

Per-stream errors are attributed to the stream that caused them: the
@Right results@ branch of the interpreter iterates the input list and
maps each empty CTE result back to the corresponding @(StreamName,
ExpectedVersion)@. Errors raised as PostgreSQL exceptions are
attributed via 'Kiroku.Store.Error.attributeMultiStreamError', which
parses the server-error detail for the offending stream name when
possible; the latent misattribution path (a future schema change that
introduces a constraint violation visible to the client) is covered
defensively.

The returned list mirrors the input order. Each 'AppendResult' carries
the corresponding stream's final state.

Empty operation input @[]@ returns @[]@ without a database round trip.
Any per-stream empty event list is rejected with
'Kiroku.Store.Error.EmptyAppendBatch' before the transaction opens.
-}
appendMultiStream ::
    (HasCallStack, Store :> es) =>
    [(StreamName, ExpectedVersion, [EventData])] ->
    Eff es [AppendResult]
appendMultiStream ops = send (AppendMultiStream ops)