| License | Apache-2.0 |
|---|---|
| Safe Haskell | None |
| Language | GHC2021 |
Singular.Provider.Koios.Client
Description
The Koios client: typed calls built from a Transport and the request
descriptions and decoders of Singular.Provider.Koios.Wire.
A transport carries one request to one raw answer — status, headers and
body — and nothing else. It does not page and it does not decode, so the
recorded transport (Singular.Provider.Koios.Recorded) and the live
HTTP transport (koios-http) hand this module the same raw answers and
every answer is paged and decoded here, once. The status is classified
here too: 2xx is an answer, 429 is rate limited, 5xx is server failing,
any other status is refused by the server — except a 400 at submittx,
which is the server's refusal of the transaction.
Every call ends in its decoded answer or in one ClientFailure naming
the call, the attempts the transport made and the evidence. An honestly
empty answer, such as an address with no outputs, is a success with an
empty list and is distinct from every failure. A requested fact absent
from an answer — a transaction, a registration, the tip — is an
UnknownFact, never a default.
Paged calls ask for an exact row total (Prefer: count=exact) and are
read in a stable order, page after page, until the total is reached or a
page comes back shorter than the limit. A page that is cut off, a page
larger than the limit, a range that does not match the page asked for, a
total that is missing or changes between pages, rows missing before the
total, or more pages than the configured ceiling each refuse the whole
call: the client never returns a shorter answer as a whole one.
Synopsis
- newtype Transport (m :: Type -> Type) = Transport {
- exchange :: RawRequest -> m Exchange
- data RawRequest = RawRequest {}
- data Retry
- data Answer = Answer {
- answerStatus :: Int
- answerHeaders :: [(Text, Text)]
- answerBody :: ByteString
- data NoAnswer
- = NoConnection Text
- | NoAnswerInTime
- | BodyCutOff Text
- | NoRecording Text
- data Exchange = Exchange {
- exchangeAttempts :: Int
- exchangeResult :: Either NoAnswer Answer
- rawRequest :: forall (a :: Access). Request a -> RawRequest
- data Koios (m :: Type -> Type) = Koios {}
- data ClientConfig = ClientConfig {
- pageSize :: Int
- pageCeiling :: Int
- defaultClientConfig :: ClientConfig
- data ClientFailure = ClientFailure {
- failureCall :: Call
- failureAttempts :: Int
- failureReason :: FailureReason
- data FailureReason
- = Unreachable Text
- | TimedOut
- | RateLimited (Maybe Int)
- | ServerFailing Int Text
- | RefusedByServer Int Text
- | IncompletePage PageRefusal
- | UnknownFact UnknownFact
- | Undecodable DecodeFailure
- | TokenFileUnreadable FilePath Text
- | TokenFileInvalid FilePath Text
- | NotRecorded Text
- data PageRefusal
- = PageCutOff Int Text
- | PageOverLimit Int Int Int
- | TotalChanged Int Integer Integer
- | TotalMissing Int (Maybe Text)
- | RangeMismatch Int Text
- | RowsMissing Integer Integer
- | PageCeilingReached Int
- data UnknownFact
- = UnknownTip
- | UnknownEpoch EpochNo
- | UnknownTransaction TxId
- | UnknownRegistration Text (Maybe Text)
- tip :: Monad m => Koios m -> m (Either ClientFailure Tip)
- addressUtxos :: Monad m => Koios m -> [Addr] -> m (Either ClientFailure [(TxIn, TxOut ConwayEra)])
- assetUtxos :: Monad m => Koios m -> [(PolicyID, AssetName)] -> m (Either ClientFailure [(TxIn, TxOut ConwayEra)])
- assetTxs :: Monad m => Koios m -> PolicyID -> AssetName -> m (Either ClientFailure [AssetTx])
- data Page (m :: Type -> Type) a
- pageRows :: Page m a -> [a]
- nextPage :: Page m a -> Maybe (m (Either ClientFailure (Page m a)))
- assetTxsPage :: Monad m => Koios m -> PolicyID -> AssetName -> m (Either ClientFailure (Page m AssetTx))
- txInfo :: Monad m => Koios m -> [TxId] -> m (Either ClientFailure [TxInfo])
- txCbor :: Monad m => Koios m -> [TxId] -> m (Either ClientFailure [TxCbor])
- epochParams :: Monad m => Koios m -> EpochNo -> m (Either ClientFailure (PParams ConwayEra))
- cliProtocolParams :: Monad m => Koios m -> m (Either ClientFailure (PParams ConwayEra))
- data SubmitOutcome
- = SubmitAccepted TxId
- | SubmitRefused Text
- submitTx :: Monad m => Koios m -> SignedTx -> m (Either ClientFailure SubmitOutcome)
- txStatus :: Monad m => Koios m -> [TxId] -> m (Either ClientFailure [TxStatus])
- accountRegistered :: Monad m => Koios m -> AccountAddress -> m (Either ClientFailure Bool)
- referenceScriptUtxos :: Monad m => Koios m -> NonEmpty ScriptHash -> m (Either ClientFailure [(ScriptHash, TxIn)])
- utxoInfo :: Monad m => Koios m -> NonEmpty TxIn -> m (Either ClientFailure [UtxoInfo])
- assetInfo :: Monad m => Koios m -> (PolicyID, AssetName) -> m (Either ClientFailure (Maybe AssetInfo))
Transport
newtype Transport (m :: Type -> Type) Source #
One request to one raw answer, in any monad.
Constructors
| Transport | |
Fields
| |
data RawRequest Source #
One HTTP request as the transport sends it.
Constructors
| RawRequest | |
Instances
| Show RawRequest Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> RawRequest -> ShowS Source # show :: RawRequest -> String Source # showList :: [RawRequest] -> ShowS Source # | |
| Eq RawRequest Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: RawRequest -> RawRequest -> Bool Source # (/=) :: RawRequest -> RawRequest -> Bool Source # | |
How a transport may retry a request.
Constructors
| RetryTransient | Retry unreachable, timed out, rate limited and server-failing answers within the transport's bounds |
| RetryUnanswered | Retry only when no answer arrived: unreachable or timed out. Submission uses this, since resending the same signed bytes cannot apply them twice, while a refusal or a server error is final. |
Instances
| Show Retry Source # | |
Defined in Singular.Provider.Koios.Client | |
| Eq Retry Source # | |
Defined in Singular.Provider.Koios.Client | |
One raw answer: status, headers with lower-case names, and body.
Constructors
| Answer | |
Fields
| |
Instances
| Show Answer Source # | |
Defined in Singular.Provider.Koios.Client | |
| Eq Answer Source # | |
Defined in Singular.Provider.Koios.Client | |
Why a transport has no answer to return.
Constructors
| NoConnection Text | Connection, DNS or TLS failure |
| NoAnswerInTime | No complete answer within the request timeout |
| BodyCutOff Text | The connection delivered fewer body bytes than announced |
| NoRecording Text | A recorded transport holds no answer for this request |
Instances
| Show NoAnswer Source # | |
Defined in Singular.Provider.Koios.Client | |
| Eq NoAnswer Source # | |
Defined in Singular.Provider.Koios.Client | |
One request's outcome after the transport's retries.
Constructors
| Exchange | |
Fields
| |
Instances
| Show Exchange Source # | |
Defined in Singular.Provider.Koios.Client | |
| Eq Exchange Source # | |
Defined in Singular.Provider.Koios.Client | |
rawRequest :: forall (a :: Access). Request a -> RawRequest Source #
The raw request of an unpaged request: its body's content type, and retries limited to unanswered requests for a submission.
Client
data Koios (m :: Type -> Type) Source #
A Koios client: a paging configuration and a transport.
Constructors
| Koios | |
Fields | |
data ClientConfig Source #
Paging configuration.
Constructors
| ClientConfig | |
Fields
| |
Instances
| Show ClientConfig Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> ClientConfig -> ShowS Source # show :: ClientConfig -> String Source # showList :: [ClientConfig] -> ShowS Source # | |
| Eq ClientConfig Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: ClientConfig -> ClientConfig -> Bool Source # (/=) :: ClientConfig -> ClientConfig -> Bool Source # | |
defaultClientConfig :: ClientConfig Source #
Pages of 1000 rows, Koios's maximum, and at most 100 pages.
Failures
data ClientFailure Source #
Why a call stopped.
Constructors
| ClientFailure | |
Fields
| |
Instances
| Show ClientFailure Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> ClientFailure -> ShowS Source # show :: ClientFailure -> String Source # showList :: [ClientFailure] -> ShowS Source # | |
| Eq ClientFailure Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: ClientFailure -> ClientFailure -> Bool Source # (/=) :: ClientFailure -> ClientFailure -> Bool Source # | |
data FailureReason Source #
The closed list of reasons a call stops.
Constructors
| Unreachable Text | Connection, DNS or TLS failure past the retry bound |
| TimedOut | No complete answer within the timeout, past the retry bound |
| RateLimited (Maybe Int) | 429 past the retry bound or beyond the wait ceiling; the last wait asked, in seconds |
| ServerFailing Int Text | 5xx past the retry bound: status and body |
| RefusedByServer Int Text | Any other 4xx, including a rejected token: status and body |
| IncompletePage PageRefusal | A page that cannot be part of a whole answer |
| UnknownFact UnknownFact | A requested fact absent from the answer |
| Undecodable DecodeFailure | An answer that does not decode |
| TokenFileUnreadable FilePath Text | The token file could not be read; no request was made |
| TokenFileInvalid FilePath Text | The file's token is outside the accepted bearer domain; nothing was sent |
| NotRecorded Text | A recorded transport holds no answer for the request |
Instances
| Show FailureReason Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> FailureReason -> ShowS Source # show :: FailureReason -> String Source # showList :: [FailureReason] -> ShowS Source # | |
| Eq FailureReason Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: FailureReason -> FailureReason -> Bool Source # (/=) :: FailureReason -> FailureReason -> Bool Source # | |
data PageRefusal Source #
Why a page cannot be part of a whole answer.
Constructors
| PageCutOff Int Text | The body at this offset is cut off or not one JSON document |
| PageOverLimit Int Int Int | The page at this offset has more rows than the limit: rows, limit |
| TotalChanged Int Integer Integer | The total at this offset differs from the first page's: first, now |
| TotalMissing Int (Maybe Text) | The answer at this offset states no exact total: its range header |
| RangeMismatch Int Text | The range header at this offset does not match the rows |
| RowsMissing Integer Integer | Fewer rows than the stated total arrived: total, received |
| PageCeilingReached Int | The configured number of pages was read and more remain |
Instances
| Show PageRefusal Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> PageRefusal -> ShowS Source # show :: PageRefusal -> String Source # showList :: [PageRefusal] -> ShowS Source # | |
| Eq PageRefusal Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: PageRefusal -> PageRefusal -> Bool Source # (/=) :: PageRefusal -> PageRefusal -> Bool Source # | |
data UnknownFact Source #
A fact the answer does not contain.
Constructors
| UnknownTip | |
| UnknownEpoch EpochNo | |
| UnknownTransaction TxId | |
| UnknownRegistration Text (Maybe Text) | The stake address had no row, or a status that is neither registered nor not registered |
Instances
| Show UnknownFact Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> UnknownFact -> ShowS Source # show :: UnknownFact -> String Source # showList :: [UnknownFact] -> ShowS Source # | |
| Eq UnknownFact Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: UnknownFact -> UnknownFact -> Bool Source # (/=) :: UnknownFact -> UnknownFact -> Bool Source # | |
Calls
addressUtxos :: Monad m => Koios m -> [Addr] -> m (Either ClientFailure [(TxIn, TxOut ConwayEra)]) Source #
Every output at the addresses, read page by page.
assetUtxos :: Monad m => Koios m -> [(PolicyID, AssetName)] -> m (Either ClientFailure [(TxIn, TxOut ConwayEra)]) Source #
Every output holding the assets, read page by page.
assetTxs :: Monad m => Koios m -> PolicyID -> AssetName -> m (Either ClientFailure [AssetTx]) Source #
Every transaction that included the asset, read page by page, in block height then transaction id order. That order makes pages stable; it is not the order in which the asset was passed on.
data Page (m :: Type -> Type) a Source #
A checked page and its deferred continuation over the same request. No subsequent HTTP exchange happens until the continuation is executed. The continuation retains the first total and the configured page ceiling; it cannot turn a cut-off answer into a shorter successful history.
nextPage :: Page m a -> Maybe (m (Either ClientFailure (Page m a))) Source #
Nothing only when this page reaches the exact advertised total.
assetTxsPage :: Monad m => Koios m -> PolicyID -> AssetName -> m (Either ClientFailure (Page m AssetTx)) Source #
Start the asset transaction listing without joining its entire history.
Each continuation uses the same Wire decoder and rangetotalrefusal
checks as assetTxs. HTTP ordering is stable height/hash order; consumers
must assemble a whole block and resolve spend dependencies before replay.
txInfo :: Monad m => Koios m -> [TxId] -> m (Either ClientFailure [TxInfo]) Source #
The named transactions, in the order asked.
txCbor :: Monad m => Koios m -> [TxId] -> m (Either ClientFailure [TxCbor]) Source #
The named transactions' bytes, in the order asked.
epochParams :: Monad m => Koios m -> EpochNo -> m (Either ClientFailure (PParams ConwayEra)) Source #
The protocol parameters of an epoch.
cliProtocolParams :: Monad m => Koios m -> m (Either ClientFailure (PParams ConwayEra)) Source #
The current protocol parameters in the node's own JSON form.
data SubmitOutcome Source #
What the server did with a submitted transaction.
Constructors
| SubmitAccepted TxId | Accepted, with the transaction id Koios returned |
| SubmitRefused Text | Refused (400), with the server's reason |
Instances
| Show SubmitOutcome Source # | |
Defined in Singular.Provider.Koios.Client Methods showsPrec :: Int -> SubmitOutcome -> ShowS Source # show :: SubmitOutcome -> String Source # showList :: [SubmitOutcome] -> ShowS Source # | |
| Eq SubmitOutcome Source # | |
Defined in Singular.Provider.Koios.Client Methods (==) :: SubmitOutcome -> SubmitOutcome -> Bool Source # (/=) :: SubmitOutcome -> SubmitOutcome -> Bool Source # | |
submitTx :: Monad m => Koios m -> SignedTx -> m (Either ClientFailure SubmitOutcome) Source #
Submit a SignedTx, whose hidden constructor requires a payment-key
witness through signTx. Serialize that
signed transaction as Conway CBOR without changing its body or witnesses.
A 400 is the server's refusal of the transaction and is returned as its
text; the transport retries the submission only when no answer arrived.
txStatus :: Monad m => Koios m -> [TxId] -> m (Either ClientFailure [TxStatus]) Source #
Confirmations of the named transactions, in the order asked. A transaction absent from the answer is not yet seen.
accountRegistered :: Monad m => Koios m -> AccountAddress -> m (Either ClientFailure Bool) Source #
Whether the reward account is registered: True or False only
when Koios says registered or not registered; no row, or any other
status, is an UnknownRegistration.
referenceScriptUtxos :: Monad m => Koios m -> NonEmpty ScriptHash -> m (Either ClientFailure [(ScriptHash, TxIn)]) Source #
Every live output whose reference script is one of the hashes, with the hash Koios names for it, read page by page. An empty answer means not found by this provider.