Package com.tuladb

Class LedgerClient

java.lang.Object
com.tuladb.LedgerClient
All Implemented Interfaces:
Closeable, AutoCloseable
public final class LedgerClient extends Object implements Closeable

  • Field Details

    • TXN_FLAG_REJECT

      public static final byte TXN_FLAG_REJECT
      Explicit-reject transfer flag (TXN_FLAG_REJECT): the engine fixes the recorded result_code to ERR_UPSTREAM_REJECTED (41); the caller's own classification is RejectCreate.reasonCode, recorded verbatim.
      See Also:

    • ERR_UPSTREAM_REJECTED

      public static final int ERR_UPSTREAM_REJECTED
      See Also:

    • ERR_AMOUNT_EXCEEDS_MAX

      public static final int ERR_AMOUNT_EXCEEDS_MAX
      The transfer's amount exceeds the ledger's max_txn_amount cap — a durable business decline; replaying the identity returns it.
      See Also:

    • ERR_HISTORY_PURGED

      public static final int ERR_HISTORY_PURGED
      This node no longer retains the transfer's history record: its history retention purged it (point lookups). The money effect and idempotency are unaffected; look the record up in the export destination. Permanent on this node, but retention is per node, so the answer can differ by node: another node may still return the record, or answer ERR_NOT_FOUND (9). Below a node's purge floor NOT_FOUND and this status both mean "not retained here", so NOT_FOUND there does not prove the transfer never existed.
      See Also:

    • ERR_ACCOUNT_CONFLICT

      public static final int ERR_ACCOUNT_CONFLICT
      A create of an existing (ledger, currency, id) whose CREATION attributes differ (an identical retry answers OK_DUPLICATE). Also answered while the engine's create guard holds the same id under another key. Deterministic: every node and every retry say the same.
      See Also:

    • RESERVED_45

      public static final int RESERVED_45
      45 and 46 are reserved for TxnRecord v2 (a retry with different fields; the effective_ts window). Never returned until v2 lands.
      See Also:

    • RESERVED_46

      public static final int RESERVED_46
      See Also:

    • ERR_EXPORT_GROUP_CONFLICT

      public static final int ERR_EXPORT_GROUP_CONFLICT
      An export page from a partition-group member was refused; the sub-code (64-75) is in the export response header, not a status. Not retryable, except sub-code 71 (retry against the leader), so it is not in FINAL_STATUSES: the status alone cannot tell 71 apart.
      See Also:

    • ERR_RECONFIG_NO_QUORUM

      public static final int ERR_RECONFIG_NO_QUORUM
      A membership change was refused by the leader's strict reconfig check: the PROPOSED voters have no live, caught-up quorum right now. Nothing was proposed. Retryable once enough of them are up, so it is not in FINAL_STATUSES.
      See Also:

    • FINAL_STATUSES

      public static final Set<Integer> FINAL_STATUSES
      Statuses that are the same answer on every node and every retry: the request itself was refused (conflicts, malformed, not permitted, breaks a ledger rule). SmartLedgerClient returns them at once instead of re-routing and retrying. Mirrors the C SDK's ledgerd_status_is_final. ERR_CONFIG (19) is deliberately NOT final: the engine also answers it for transient, never-executed cases. NOT_FOUND (9) is not final either: a lagging node may not have the record yet.

    • RETRYABLE_STATUSES

      public static final Set<Integer> RETRYABLE_STATUSES
      Statuses that mean the server shed load or hit a transient failure and NOTHING was written: back off and retry with the SAME identity (txnId / transfer id); the engine's duplicate check makes the retry safe whichever attempt landed. Mirrors the C SDK's ledgerd_status_is_retryable and contracts/status-codes.env (class retryable). A status in neither this set nor FINAL_STATUSES (NOT_FOUND, ERR_CONFIG, an inactive account, an unknown code...) depends on state that can change: SmartLedgerClient still retries it after a leader refresh, but a caller retrying by hand should look at the status first.

    • AMBIGUOUS_STATUSES

      public static final Set<Integer> AMBIGUOUS_STATUSES
      Statuses that are transient but leave the outcome UNKNOWN: the write may have committed (contracts/status-codes.env, class ambiguous): 12 ERR_QUORUM_TIMEOUT, which a leader that lost quorum or leadership mid-write answers without knowing the outcome. Retry only with the SAME identity (txnId, transfer id, an explicit ledger id), whose replay answers the original's outcome (OK_DUPLICATE if it landed). Never resend an operation with no identity: SmartLedgerClient returns it with a message starting "outcome unknown".

    • REJECT_REASON_ENGINE_BASE

      public static final int REJECT_REASON_ENGINE_BASE
      Engine-owned reject reason codes. rejectReasonCode is normally YOUR taxonomy, recorded verbatim on an explicit reject; the top of the u32 space is reserved for the engine so an engine-originated decline carries a reason no caller can collide with (a caller supplying one is refused). Encoding: 0xFFFF0000 | status.
      See Also:

    • REJECT_REASON_AMOUNT_EXCEEDS_MAX

      public static final int REJECT_REASON_AMOUNT_EXCEEDS_MAX
      See Also:

    • REJECT_ERR_WIRE_PARSE

      public static final int REJECT_ERR_WIRE_PARSE
      R3-M4: split overloaded ERR_CONFIG into specific codes. - REJECT_ERR_WIRE_PARSE: wire-level decode failed (short payload, malformed batch). The request as sent is broken; the client needs to fix the payload, not resend it. - REJECT_ERR_WRONG_MODE: the ledger mode doesn't allow this operation (e.g. tiered op against a default ledger). The remaining REJECT_ERR_CONFIG=19 cases are genuine server- side config validation errors. See engine include/ledger_types.h for the canonical contract.
      See Also:

    • REJECT_ERR_WRONG_MODE

      public static final int REJECT_ERR_WRONG_MODE
      See Also:

    • REJECT_ERR_DEADLINE_EXCEEDED

      public static final int REJECT_ERR_DEADLINE_EXCEEDED
      See Also:

    • REJECT_ERR_RESERVE_EXPIRED

      public static final int REJECT_ERR_RESERVE_EXPIRED
      reserve-expiry: commit/rollback of a reservation that lapsed past its deadline (the hold was released; it resolved to phase EXPIRED = 3).
      See Also:

    • TXN_BATCH_MAX

      public static final int TXN_BATCH_MAX
      See Also:

    • MAX_PIPELINE_DEPTH

      public static final int MAX_PIPELINE_DEPTH
      Ceiling on the pipeline window, matching LEDGERD_MAX_PIPELINE_DEPTH in the C SDK. The send loop pushes the whole window before reading any of it, so an unbounded depth deadlocks: once the server's receive buffer and our send buffer are both full, the server blocks writing responses nobody is reading while we block writing requests it cannot accept -- and the io lock is held throughout. Depth only buys round-trip overlap, which saturates long before this ceiling.
      See Also:

    • MAX_RESPONSE_PAYLOAD_BYTES

      public static final int MAX_RESPONSE_PAYLOAD_BYTES
      See Also:

  • Constructor Details

    • LedgerClient

      public LedgerClient(String host, int port, int timeoutMs)
      Legacy form: timeoutMs bounds connect, read and write alike.

    • LedgerClient

      public LedgerClient(String host, int port, LedgerClient.Timeouts timeouts)
      Explicit timeouts; TLS and the plaintext opt-in from the environment.

    • LedgerClient

      public LedgerClient(String host, int port, LedgerClient.Timeouts timeouts, boolean useIso20022RefSize, LedgerClient.TlsOptions tlsOptions)

    • LedgerClient

      public LedgerClient(String host, int port, int timeoutMs, boolean useIso20022RefSize)

    • LedgerClient

      public LedgerClient(String host, int port, int timeoutMs, boolean useIso20022RefSize, LedgerClient.TlsOptions tlsOptions)

    • LedgerClient

      public LedgerClient(String host, int port, int timeoutMs, boolean useIso20022RefSize, LedgerClient.TlsOptions tlsOptions, boolean allowPlaintext)
      Parameters:
      allowPlaintext - accept cleartext ledger traffic to a non-loopback host. The other constructors read TULADB_CLIENT_ALLOW_PLAINTEXT instead; this one puts the choice at the call site, where a code review can see it.

    • LedgerClient

      public LedgerClient(String host, int port, LedgerClient.Timeouts timeouts, boolean useIso20022RefSize, LedgerClient.TlsOptions tlsOptions, boolean allowPlaintext)

  • Method Details