Documentation ¶
Index ¶
- type Base64Ledger
- type CaptiveAiBlocksCore
- func (c *CaptiveAiBlocksCore) Close() error
- func (c *CaptiveAiBlocksCore) GetLatestLedgerSequence() (uint32, error)
- func (c *CaptiveAiBlocksCore) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
- func (c *CaptiveAiBlocksCore) IsPrepared(ledgerRange Range) (bool, error)
- func (c *CaptiveAiBlocksCore) PrepareRange(ledgerRange Range) error
- type DatabaseBackend
- func (dbb *DatabaseBackend) Close() error
- func (dbb *DatabaseBackend) GetLatestLedgerSequence() (uint32, error)
- func (dbb *DatabaseBackend) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
- func (*DatabaseBackend) IsPrepared(ledgerRange Range) (bool, error)
- func (dbb *DatabaseBackend) PrepareRange(ledgerRange Range) error
- type HistoryArchiveBackend
- func (hab *HistoryArchiveBackend) Close() error
- func (hab *HistoryArchiveBackend) GetLatestLedgerSequence() (uint32, error)
- func (hab *HistoryArchiveBackend) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
- func (hab *HistoryArchiveBackend) IsPrepared(ledgerRange Range) (bool, error)
- func (hab *HistoryArchiveBackend) PrepareRange(ledgerRange Range) error
- type LatestLedgerSequenceResponse
- type LedgerBackend
- type LedgerResponse
- type MockDatabaseBackend
- func (m *MockDatabaseBackend) Close() error
- func (m *MockDatabaseBackend) GetLatestLedgerSequence() (uint32, error)
- func (m *MockDatabaseBackend) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
- func (m *MockDatabaseBackend) IsPrepared(ledgerRange Range) (bool, error)
- func (m *MockDatabaseBackend) PrepareRange(ledgerRange Range) error
- type PrepareRangeResponse
- type Range
- type RemoteCaptiveAiBlocksCore
- func (c RemoteCaptiveAiBlocksCore) Close() error
- func (c RemoteCaptiveAiBlocksCore) GetLatestLedgerSequence() (sequence uint32, err error)
- func (c RemoteCaptiveAiBlocksCore) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
- func (c RemoteCaptiveAiBlocksCore) IsPrepared(ledgerRange Range) (bool, error)
- func (c RemoteCaptiveAiBlocksCore) PrepareRange(ledgerRange Range) error
- type RemoteCaptiveOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Base64Ledger ¶
type Base64Ledger xdr.LedgerCloseMeta
Base64Ledger extends xdr.LedgerCloseMeta with JSON encoding and decoding
func (Base64Ledger) MarshalJSON ¶
func (r Base64Ledger) MarshalJSON() ([]byte, error)
func (*Base64Ledger) UnmarshalJSON ¶
func (r *Base64Ledger) UnmarshalJSON(b []byte) error
type CaptiveAiBlocksCore ¶
type CaptiveAiBlocksCore struct {
// contains filtered or unexported fields
}
CaptiveAiBlocksCore is a ledger backend that starts internal AiBlocks-Core subprocess responsible for streaming ledger data. It provides better decoupling than DatabaseBackend but requires some extra init time.
It operates in two modes:
- When a BoundedRange is prepared it starts AiBlocks-Core in catchup mode that replays ledgers in memory. This is very fast but requires AiBlocks-Core to keep ledger state in RAM. It requires around 3GB of RAM as of August 2020.
- When a UnboundedRange is prepared it runs AiBlocks-Core catchup mode to sync with the first ledger and then runs it in a normal mode. This requires the configPath to be provided because a database connection is required and quorum set needs to be selected.
The database requirement for UnboundedRange will soon be removed when some changes are implemented in AiBlocks-Core.
When running CaptiveAiBlocksCore will create a temporary folder to store bucket files and other temporary files. The folder is removed when Close is called.
The communication is performed via filesystem pipe which is created in a temporary folder.
Currently BoundedRange requires a full-trust on history archive. This issue is being fixed in AiBlocks-Core.
While using BoundedRanges is straightforward there are a few gotchas connected to UnboundedRanges:
- PrepareRange takes more time because all ledger entries must be stored on disk instead of RAM.
- If GetLedger is not called frequently (every 5 sec. on average) the AiBlocks-Core process can go out of sync with the network. This happens because there is no buffering of communication pipe and CaptiveAiBlocksCore has a very small internal buffer and AiBlocks-Core will not close the new ledger if it's not read.
Requires AiBlocks-Core v13.2.0+.
func NewCaptive ¶
func NewCaptive(executablePath, configPath, networkPassphrase string, historyURLs []string) (*CaptiveAiBlocksCore, error)
NewCaptive returns a new CaptiveAiBlocksCore.
All parameters are required, except configPath which is not required when working with BoundedRanges only.
func (*CaptiveAiBlocksCore) Close ¶
func (c *CaptiveAiBlocksCore) Close() error
Close closes existing AiBlocks-Core process, streaming sessions and removes all temporary files.
func (*CaptiveAiBlocksCore) GetLatestLedgerSequence ¶
func (c *CaptiveAiBlocksCore) GetLatestLedgerSequence() (uint32, error)
GetLatestLedgerSequence returns the sequence of the latest ledger available in the backend. This method returns an error if not in a session (start with PrepareRange).
Note that for UnboundedRange the returned sequence number is not necessarily the latest sequence closed by the network. It's always the last value available in the backend.
func (*CaptiveAiBlocksCore) GetLedger ¶
func (c *CaptiveAiBlocksCore) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
GetLedger returns true when ledger is found and it's LedgerCloseMeta. Call PrepareRange first to instruct the backend which ledgers to fetch.
CaptiveAiBlocksCore requires PrepareRange call first to initialize AiBlocks-Core. Requesting a ledger on non-prepared backend will return an error.
Because data is streamed from AiBlocks-Core ledger after ledger user should request sequences in a non-decreasing order. If the requested sequence number is less than the last requested sequence number, an error will be returned.
This function behaves differently for bounded and unbounded ranges:
- BoundedRange makes GetLedger blocking if the requested ledger is not yet available in the ledger. After getting the last ledger in a range this method will also Close() the backend.
- UnboundedRange makes GetLedger non-blocking. The method will return with the first argument equal false.
This is done to provide maximum performance when streaming old ledgers.
func (*CaptiveAiBlocksCore) IsPrepared ¶
func (c *CaptiveAiBlocksCore) IsPrepared(ledgerRange Range) (bool, error)
IsPrepared returns true if a given ledgerRange is prepared.
func (*CaptiveAiBlocksCore) PrepareRange ¶
func (c *CaptiveAiBlocksCore) PrepareRange(ledgerRange Range) error
PrepareRange prepares the given range (including from and to) to be loaded. Captive aiblocks-core backend needs to initalize AiBlocks-Core state to be able to stream ledgers. AiBlocks-Core mode depends on the provided ledgerRange:
- For BoundedRange it will start AiBlocks-Core in catchup mode.
- For UnboundedRange it will first catchup to starting ledger and then run it normally (including connecting to the AiBlocks network).
Please note that using a BoundedRange, currently, requires a full-trust on history archive. This issue is being fixed in AiBlocks-Core.
type DatabaseBackend ¶
type DatabaseBackend struct {
// contains filtered or unexported fields
}
DatabaseBackend implements a database data store.
func NewDatabaseBackend ¶
func NewDatabaseBackend(dataSourceName, networkPassphrase string) (*DatabaseBackend, error)
func NewDatabaseBackendFromSession ¶
func NewDatabaseBackendFromSession(session *db.Session, networkPassphrase string) (*DatabaseBackend, error)
func (*DatabaseBackend) Close ¶
func (dbb *DatabaseBackend) Close() error
Close disconnects an active database session.
func (*DatabaseBackend) GetLatestLedgerSequence ¶
func (dbb *DatabaseBackend) GetLatestLedgerSequence() (uint32, error)
GetLatestLedgerSequence returns the most recent ledger sequence number present in the database.
func (*DatabaseBackend) GetLedger ¶
func (dbb *DatabaseBackend) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
GetLedger returns the LedgerCloseMeta for the given ledger sequence number. The first returned value is false when the ledger does not exist in the database.
func (*DatabaseBackend) IsPrepared ¶
func (*DatabaseBackend) IsPrepared(ledgerRange Range) (bool, error)
IsPrepared returns true if a given ledgerRange is prepared.
func (*DatabaseBackend) PrepareRange ¶
func (dbb *DatabaseBackend) PrepareRange(ledgerRange Range) error
type HistoryArchiveBackend ¶
type HistoryArchiveBackend struct {
// contains filtered or unexported fields
}
HistoryArchiveBackend is using history archives to get ledger data. Please remember that:
- history archives do not contain meta changes so meta fields in LedgerCloseMeta will be empty,
- history archives should not be trusted: ledger data is not signed!
func NewHistoryArchiveBackendFromArchive ¶
func NewHistoryArchiveBackendFromArchive(archive historyarchive.ArchiveInterface) *HistoryArchiveBackend
NewHistoryArchiveBackendFromArchive builds a new HistoryArchiveBackend using historyarchive.Archive.
func NewHistoryArchiveBackendFromURL ¶
func NewHistoryArchiveBackendFromURL(archiveURL string) (*HistoryArchiveBackend, error)
NewHistoryArchiveBackendFromURL builds a new HistoryArchiveBackend using history archive URL.
func (*HistoryArchiveBackend) Close ¶
func (hab *HistoryArchiveBackend) Close() error
Close clears and resets internal state.
func (*HistoryArchiveBackend) GetLatestLedgerSequence ¶
func (hab *HistoryArchiveBackend) GetLatestLedgerSequence() (uint32, error)
GetLatestLedgerSequence returns the most recent ledger sequence number present in the history archives.
func (*HistoryArchiveBackend) GetLedger ¶
func (hab *HistoryArchiveBackend) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
GetLedger returns the LedgerCloseMeta for the given ledger sequence number. The first returned value is false when the ledger does not exist in the history archives. Due to the history archives architecture the first request to get a ledger is slow because it downloads the data for all the ledgers for a given checkpoint. The following requests for other ledgers within the same checkpoint are fast, requesting another checkpoint is slow again.
func (*HistoryArchiveBackend) IsPrepared ¶
func (hab *HistoryArchiveBackend) IsPrepared(ledgerRange Range) (bool, error)
IsPrepared returns true if a given ledgerRange is prepared.
func (*HistoryArchiveBackend) PrepareRange ¶
func (hab *HistoryArchiveBackend) PrepareRange(ledgerRange Range) error
PrepareRange does nothing because of how history archives are structured. Request any ledger by using `GetLedger` to download all ledger data within a given checkpoint
type LatestLedgerSequenceResponse ¶
type LatestLedgerSequenceResponse struct {
Sequence uint32 `json:"sequence"`
}
LatestLedgerSequenceResponse is the response for the GetLatestLedgerSequence command.
type LedgerBackend ¶
type LedgerBackend interface { // GetLatestLedgerSequence returns the sequence of the latest ledger available // in the backend. GetLatestLedgerSequence() (sequence uint32, err error) // The first returned value is false when the ledger does not exist in a backend. GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error) // PrepareRange prepares the given range (including from and to) to be loaded. // Some backends (like captive aiblocks-core) need to initalize data to be // able to stream ledgers. Blocks until the first ledger is available. PrepareRange(ledgerRange Range) error // IsPrepared returns true if a given ledgerRange is prepared. IsPrepared(ledgerRange Range) (bool, error) Close() error }
LedgerBackend represents the interface to a ledger data store.
type LedgerResponse ¶
type LedgerResponse struct { Present bool `json:"present"` Ledger Base64Ledger `json:"ledger"` }
LedgerResponse is the response for the GetLedger command.
type MockDatabaseBackend ¶
func (*MockDatabaseBackend) Close ¶
func (m *MockDatabaseBackend) Close() error
func (*MockDatabaseBackend) GetLatestLedgerSequence ¶
func (m *MockDatabaseBackend) GetLatestLedgerSequence() (uint32, error)
func (*MockDatabaseBackend) GetLedger ¶
func (m *MockDatabaseBackend) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
func (*MockDatabaseBackend) IsPrepared ¶
func (m *MockDatabaseBackend) IsPrepared(ledgerRange Range) (bool, error)
func (*MockDatabaseBackend) PrepareRange ¶
func (m *MockDatabaseBackend) PrepareRange(ledgerRange Range) error
type PrepareRangeResponse ¶
type PrepareRangeResponse struct { LedgerRange Range `json:"ledgerRange"` StartTime time.Time `json:"startTime"` Ready bool `json:"ready"` ReadyDuration int `json:"readyDuration"` }
PrepareRangeResponse describes the status of the pending PrepareRange operation.
type Range ¶
type Range struct {
// contains filtered or unexported fields
}
Range represents a range of ledger sequence numbers.
func BoundedRange ¶
BoundedRange constructs a bounded range of ledgers with a fixed starting ledger and ending ledger.
func SingleLedgerRange ¶
SingleLedgerRange constructs a bounded range containing a single ledger.
func UnboundedRange ¶
BoundedRange constructs a unbounded range of ledgers with a fixed starting ledger.
func (Range) MarshalJSON ¶
func (*Range) UnmarshalJSON ¶
type RemoteCaptiveAiBlocksCore ¶
type RemoteCaptiveAiBlocksCore struct {
// contains filtered or unexported fields
}
RemoteCaptiveAiBlocksCore is an http client for interacting with a remote captive core server.
func NewRemoteCaptive ¶
func NewRemoteCaptive(captiveCoreURL string, options ...RemoteCaptiveOption) (RemoteCaptiveAiBlocksCore, error)
NewRemoteCaptive returns a new RemoteCaptiveAiBlocksCore instance.
Only the captiveCoreURL parameter is required.
func (RemoteCaptiveAiBlocksCore) Close ¶
func (c RemoteCaptiveAiBlocksCore) Close() error
Close cancels any pending PrepareRange requests.
func (RemoteCaptiveAiBlocksCore) GetLatestLedgerSequence ¶
func (c RemoteCaptiveAiBlocksCore) GetLatestLedgerSequence() (sequence uint32, err error)
GetLatestLedgerSequence returns the sequence of the latest ledger available in the backend. This method returns an error if not in a session (start with PrepareRange).
Note that for UnboundedRange the returned sequence number is not necessarily the latest sequence closed by the network. It's always the last value available in the backend.
func (RemoteCaptiveAiBlocksCore) GetLedger ¶
func (c RemoteCaptiveAiBlocksCore) GetLedger(sequence uint32) (bool, xdr.LedgerCloseMeta, error)
GetLedger returns true when ledger is found and it's LedgerCloseMeta. Call PrepareRange first to instruct the backend which ledgers to fetch.
CaptiveAiBlocksCore requires PrepareRange call first to initialize AiBlocks-Core. Requesting a ledger on non-prepared backend will return an error.
Because data is streamed from AiBlocks-Core ledger after ledger user should request sequences in a non-decreasing order. If the requested sequence number is less than the last requested sequence number, an error will be returned.
This function behaves differently for bounded and unbounded ranges:
- BoundedRange makes GetLedger blocking if the requested ledger is not yet available in the ledger. After getting the last ledger in a range this method will also Close() the backend.
- UnboundedRange makes GetLedger non-blocking. The method will return with the first argument equal false.
This is done to provide maximum performance when streaming old ledgers.
func (RemoteCaptiveAiBlocksCore) IsPrepared ¶
func (c RemoteCaptiveAiBlocksCore) IsPrepared(ledgerRange Range) (bool, error)
IsPrepared returns true if a given ledgerRange is prepared.
func (RemoteCaptiveAiBlocksCore) PrepareRange ¶
func (c RemoteCaptiveAiBlocksCore) PrepareRange(ledgerRange Range) error
PrepareRange prepares the given range (including from and to) to be loaded. Captive aiblocks-core backend needs to initalize AiBlocks-Core state to be able to stream ledgers. AiBlocks-Core mode depends on the provided ledgerRange:
- For BoundedRange it will start AiBlocks-Core in catchup mode.
- For UnboundedRange it will first catchup to starting ledger and then run it normally (including connecting to the AiBlocks network).
Please note that using a BoundedRange, currently, requires a full-trust on history archive. This issue is being fixed in AiBlocks-Core.
type RemoteCaptiveOption ¶
type RemoteCaptiveOption func(c *RemoteCaptiveAiBlocksCore)
RemoteCaptiveOption values can be passed into NewRemoteCaptive to customize a RemoteCaptiveAiBlocksCore instance.
func PrepareRangePollInterval ¶
func PrepareRangePollInterval(d time.Duration) RemoteCaptiveOption
PrepareRangePollInterval configures how often the captive core server will be polled when blocking on the PrepareRange operation.