actions

Documentation

Overview

Package actions provides the infrastructure for defining and executing actions (code that is triggered in response to an client request) on aurora. At present it allows for defining actions that can respond using JSON or SSE.

Index

• Constants
• func AccountInfo(ctx context.Context, cq *core.Q, addr string) (*protocol.Account, error)
• func AccountPage(ctx context.Context, hq history.QSigners, signer string, pq db2.PageQuery) (hal.Page, error)
• func StreamTransactions(ctx context.Context, s *sse.Stream, hq *history.Q, accountID string, ...) error
• func TransactionPage(ctx context.Context, hq *history.Q, accountID string, ledgerID int32, ...) (hal.Page, error)
• func TransactionResource(ctx context.Context, hq *history.Q, txHash string) (aurora.Transaction, error)
• type Base
  • func (base *Base) Do(fns ...func())
  • func (base *Base) Execute(action interface{})
  • func (base *Base) GetAccountID(name string) (result xdr.AccountId)
  • func (base *Base) GetAddress(name string, opts ...Opt) (result string)
  • func (base *Base) GetAmount(name string) (result xdr.Int64)
  • func (base *Base) GetAsset(prefix string) (result xdr.Asset)
  • func (base *Base) GetAssetType(name string) xdr.AssetType
  • func (base *Base) GetBool(name string) bool
  • func (base *Base) GetCursor(name string) string
  • func (base *Base) GetInt32(name string) int32
  • func (base *Base) GetInt64(name string) int64
  • func (base *Base) GetLimit(name string, def uint64, max uint64) uint64
  • func (base *Base) GetPageQuery(opts ...Opt) db2.PageQuery
  • func (base *Base) GetPositiveAmount(name string) (result xdr.Int64)
  • func (base *Base) GetString(name string) string
  • func (base *Base) GetStringFromURLParam(name string) string
  • func (base *Base) GetTimeMillis(name string) (timeMillis time.Millis)
  • func (base *Base) GetURLParam(key string) (string, bool)
  • func (base *Base) MaybeGetAsset(prefix string) (xdr.Asset, bool)
  • func (base *Base) Path() string
  • func (base *Base) Prepare(w http.ResponseWriter, r *http.Request, appCtx context.Context, ...)
  • func (base *Base) SetInvalidField(name string, reason error)
  • func (base *Base) Setup(fns ...func())
  • func (base *Base) ValidateBodyType()
• type EventStreamer
• type JSONer
• type Opt
• type RateLimiterProvider
• type RawDataResponder
• type SingleObjectStreamer

Constants

const (
	// ParamCursor is a query string param name
	ParamCursor = "cursor"
	// ParamOrder is a query string param name
	ParamOrder = "order"
	// ParamLimit is a query string param name
	ParamLimit = "limit"
)

TODO: move these constants to urlparam.go as we should parse the params with http handlers in the upper level package.

Functions

func AccountInfo

func AccountInfo(ctx context.Context, cq *core.Q, addr string) (*protocol.Account, error)

AccountInfo returns the information about an account identified by addr.

func AccountPage

func AccountPage(ctx context.Context, hq history.QSigners, signer string, pq db2.PageQuery) (hal.Page, error)

AccountPage returns a page containing the account records that have `signer` as a signer. This doesn't return full account details resource because of the limitations of existing ingestion architecture. In a future, when the new ingestion system is fully integrated, this endpoint can be used to find accounts for signer but also accounts for assets, home domain, inflation_dest etc.

func StreamTransactions

func StreamTransactions(ctx context.Context, s *sse.Stream, hq *history.Q, accountID string, ledgerID int32, includeFailedTx bool, pq db2.PageQuery) error

StreamTransactions streams transaction records of an account/ledger identified by accountID/ledgerID based on pq and includeFailedTx.

func TransactionPage

func TransactionPage(ctx context.Context, hq *history.Q, accountID string, ledgerID int32, includeFailedTx bool, pq db2.PageQuery) (hal.Page, error)

TransactionPage returns a page containing the transaction records of an account/ledger identified by accountID/ledgerID into a page based on pq and includeFailedTx.

func TransactionResource

func TransactionResource(ctx context.Context, hq *history.Q, txHash string) (aurora.Transaction, error)

TransactionResource returns a single transaction resource identified by txHash.

Types

type Base

type Base struct {
	W   http.ResponseWriter
	R   *http.Request
	Err error
	// contains filtered or unexported fields
}

Base is a helper struct you can use as part of a custom action via composition.

TODO: example usage

func (*Base) Do

func (base *Base) Do(fns ...func())

Do executes the provided func iff there is no current error for the action. Provides a nicer way to invoke a set of steps that each may set `action.Err` during execution

func (*Base) Execute

func (base *Base) Execute(action interface{})

Execute trigger content negotiation and the actual execution of one of the action's handlers.

func (*Base) GetAccountID

func (base *Base) GetAccountID(name string) (result xdr.AccountId)

GetAccountID retireves an xdr.AccountID by attempting to decode a diamnet address at the provided name.

func (*Base) GetAddress

func (base *Base) GetAddress(name string, opts ...Opt) (result string)

GetAddress retrieves a diamnet address. It confirms the value loaded is a valid diamnet address, setting an invalid field error if it is not.

func (*Base) GetAmount

func (base *Base) GetAmount(name string) (result xdr.Int64)

GetAmount returns a native amount (i.e. 64-bit integer) by parsing the string at the provided name in accordance with the diamnet client conventions

func (*Base) GetAsset

func (base *Base) GetAsset(prefix string) (result xdr.Asset)

GetAsset decodes an asset from the request fields prefixed by `prefix`. To succeed, three prefixed fields must be present: asset_type, asset_code, and asset_issuer.

func (*Base) GetAssetType

func (base *Base) GetAssetType(name string) xdr.AssetType

GetAssetType is a helper that returns a xdr.AssetType by reading a string

func (*Base) GetBool

func (base *Base) GetBool(name string) bool

GetBool retrieves a bool from the query parameter for the given name. Populates err if the value is not a valid bool. Defaults to `false` in case of an empty string. WARNING, do not change this behaviour without checking other modules, ex. this is critical that failed transactions are not included (`false`) by default.

func (*Base) GetCursor

func (base *Base) GetCursor(name string) string

GetCursor retrieves a string from either the URLParams, form or query string. This method uses the priority (URLParams, Form, Query).

func (*Base) GetInt32

func (base *Base) GetInt32(name string) int32

GetInt32 retrieves an int32 from the action parameter of the given name. Populates err if the value is not a valid int32

func (*Base) GetInt64

func (base *Base) GetInt64(name string) int64

GetInt64 retrieves an int64 from the action parameter of the given name. Populates err if the value is not a valid int64

func (*Base) GetLimit

func (base *Base) GetLimit(name string, def uint64, max uint64) uint64

GetLimit retrieves a uint64 limit from the action parameter of the given name. Populates err if the value is not a valid limit. Uses the provided default value if the limit parameter is a blank string.

func (*Base) GetPageQuery

func (base *Base) GetPageQuery(opts ...Opt) db2.PageQuery

GetPageQuery is a helper that returns a new db.PageQuery struct initialized using the results from a call to GetPagingParams()

func (*Base) GetPositiveAmount

func (base *Base) GetPositiveAmount(name string) (result xdr.Int64)

GetPositiveAmount returns a native amount (i.e. 64-bit integer) by parsing the string at the provided name in accordance with the diamnet client conventions. Renders error for negative amounts and zero.

func (*Base) GetString

func (base *Base) GetString(name string) string

GetString retrieves a string from either the URLParams, form or query string. This method uses the priority (URLParams, Form, Query).

func (*Base) GetStringFromURLParam

func (base *Base) GetStringFromURLParam(name string) string

GetStringFromURLParam retrieves a string from the URLParams.

func (*Base) GetTimeMillis

func (base *Base) GetTimeMillis(name string) (timeMillis time.Millis)

GetTimeMillis retrieves a TimeMillis from the action parameter of the given name. Populates err if the value is not a valid TimeMillis

func (*Base) GetURLParam

func (base *Base) GetURLParam(key string) (string, bool)

GetURLParam returns the corresponding URL parameter value from the request routing context and an additional boolean reflecting whether or not the param was found. This is ported from Chi since the Chi version returns "" for params not found. This is undesirable since "" also is a valid url param. Ref: https://github.com/go-chi/chi/blob/d132b31857e5922a2cc7963f4fcfd8f46b3f2e97/context.go#L69

func (*Base) MaybeGetAsset

func (base *Base) MaybeGetAsset(prefix string) (xdr.Asset, bool)

MaybeGetAsset decodes an asset from the request fields as GetAsset does, but only if type field is populated. returns an additional boolean reflecting whether or not the decoding was performed

func (*Base) Path

func (base *Base) Path() string

Path returns the current action's path, as determined by the http.Request of this action

func (*Base) Prepare

func (base *Base) Prepare(w http.ResponseWriter, r *http.Request, appCtx context.Context, sseUpdateFrequency time.Duration)

Prepare established the common attributes that get used in nearly every action. "Child" actions may override this method to extend action, but it is advised you also call this implementation to maintain behavior.

func (*Base) SetInvalidField

func (base *Base) SetInvalidField(name string, reason error)

SetInvalidField establishes an error response triggered by an invalid input field from the user.

func (*Base) Setup

func (base *Base) Setup(fns ...func())

Setup runs the provided funcs if and only if no call to Setup() has been made previously on this action.

func (*Base) ValidateBodyType

func (base *Base) ValidateBodyType()

ValidateBodyType sets an error on the action if the requests Content-Type

is not `application/x-www-form-urlencoded`

type EventStreamer

type EventStreamer interface {
	SSE(*sse.Stream) error
}

EventStreamer implementors can respond to a request whose response type was negotiated to be MimeEventStream.

type JSONer

type JSONer interface {
	JSON() error
}

JSONer implementors can respond to a request whose response type was negotiated to be MimeHal or MimeJSON.

type Opt

type Opt int

const (
	// DisableCursorValidation disables cursor validation in GetPageQuery
	DisableCursorValidation Opt = iota
	// RequiredParam is used in Get* methods and defines a required parameter
	// (errors if value is empty).
	RequiredParam
)

type RateLimiterProvider

type RateLimiterProvider interface {
	GetRateLimiter() *throttled.HTTPRateLimiter
}

RateLimiterProvider is an interface that provides access to the type's HTTPRateLimiter.

type RawDataResponder

type RawDataResponder interface {
	Raw() error
}

RawDataResponder implementors can respond to a request whose response type was negotiated to be MimeRaw.

type SingleObjectStreamer

type SingleObjectStreamer interface {
	LoadEvent() (sse.Event, error)
}

SingleObjectStreamer implementors can respond to a request whose response type was negotiated to be MimeEventStream. A SingleObjectStreamer loads an object whenever a ledger is closed.