actions

package
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 3, 2020 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
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"
	// LastLedgerHeaderName is the header which is set on all endpoints
	LastLedgerHeaderName = "Latest-Ledger"
)

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

Variables

This section is empty.

Functions

func AccountInfo 

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

AccountInfo returns the information about an account identified by addr.

func FullURL 

func FullURL(ctx context.Context) *url.URL

FullURL returns a URL containing the information regarding the original request stored in the context.

func GetAccountID 

func GetAccountID(r *http.Request, name string) (xdr.AccountId, error)

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

func GetAsset 

func GetAsset(r *http.Request, prefix string) (xdr.Asset, error)

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 GetAssets 

func GetAssets(r *http.Request, name string) ([]xdr.Asset, error)

GetAssets parses a list of assets from a given request. The request parameter is expected to be a comma separated list of assets encoded in the format (Code:Issuer or "native") defined by SEP-0011 https://github.com/stellar/stellar-protocol/pull/313 If there is no request parameter present GetAssets will return an empty list of assets

func GetCursor 

func GetCursor(r *http.Request, name string) (string, error)

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

func GetInt64 

func GetInt64(r *http.Request, name string) (int64, error)

GetInt64 retrieves an int64 from the action parameter of the given name.

func GetLimit 

func GetLimit(r *http.Request, name string, def uint64, max uint64) (uint64, error)

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 GetPageQuery 

func GetPageQuery(r *http.Request, opts ...Opt) (db2.PageQuery, error)

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

func GetParams 

func GetParams(dst interface{}, r *http.Request) error

GetParams fills a struct with values read from a request's query parameters.

func GetPositiveAmount 

func GetPositiveAmount(r *http.Request, fieldName string) (xdr.Int64, error)

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

func GetString 

func GetString(r *http.Request, name string) (string, error)

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

func GetStringFromURLParam 

func GetStringFromURLParam(r *http.Request, name string) (string, error)

GetStringFromURLParam retrieves a string from the URLParams.

func GetTransactionID 

func GetTransactionID(r *http.Request, name string) (string, error)

GetTransactionID retireves a transaction identifier by attempting to decode an hex-encoded, 64-digit lowercase string at the provided name.

func GetURIParams 

func GetURIParams(query interface{}, paginated bool) []string

GetURIParams returns a list of query parameters for a given query struct

func GetURLParam 

func GetURLParam(r *http.Request, 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 HistoryQFromRequest 

func HistoryQFromRequest(request *http.Request) (*history.Q, error)

func MaybeGetAsset 

func MaybeGetAsset(r *http.Request, 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 SetLastLedgerHeader 

func SetLastLedgerHeader(w HeaderWriter, lastLedger uint32)

SetLastLedgerHeader sets the Latest-Ledger header

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) (horizon.Transaction, error)

TransactionResource returns a single transaction resource identified by txHash.

func ValidateAssetParams 

func ValidateAssetParams(aType, code, issuer, prefix string) error

ValidateAssetParams runs multiple checks on an asset query parameter

func ValidateCursorWithinHistory 

func ValidateCursorWithinHistory(pq db2.PageQuery) error

ValidateCursorWithinHistory compares the requested page of data against the ledger state of the history database. In the event that the cursor is guaranteed to return no results, we return a 410 GONE http response.

Types

type AccountOffersQuery 

type AccountOffersQuery struct {
	AccountID string `schema:"account_id" valid:"accountID,required"`
}

AccountOffersQuery query struct for offers end-point

type AccountsQuery 

type AccountsQuery struct {
	Signer      string `schema:"signer" valid:"accountID,optional"`
	AssetFilter string `schema:"asset" valid:"asset,optional"`
}

AccountsQuery query struct for accounts end-point

func (AccountsQuery) Asset 

func (q AccountsQuery) Asset() *xdr.Asset

Asset returns an xdr.Asset representing the Asset we want to find the trustees by.

func (AccountsQuery) URITemplate 

func (q AccountsQuery) URITemplate() string

URITemplate returns a rfc6570 URI template the query struct

func (AccountsQuery) Validate 

func (q AccountsQuery) Validate() error

Validate runs custom validations.

type AssetStatsHandler 

type AssetStatsHandler struct {
}

AssetStatsHandler is the action handler for the /asset endpoint

func (AssetStatsHandler) GetResourcePage 

func (handler AssetStatsHandler) GetResourcePage(
	w HeaderWriter,
	r *http.Request,
) ([]hal.Pageable, error)

GetResourcePage returns a page of offers.

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 stellar address at the provided name.

func (*Base) GetAddress 

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

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

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) 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) (cursor 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) (limit 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) (result db2.PageQuery)

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

func (*Base) GetString 

func (base *Base) GetString(name string) (result 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 GetAccountOffersHandler 

type GetAccountOffersHandler struct {
}

GetAccountOffersHandler is the action handler for the `/accounts/{account_id}/offers` endpoint when using experimental ingestion.

func (GetAccountOffersHandler) GetResourcePage 

func (handler GetAccountOffersHandler) GetResourcePage(
	w HeaderWriter,
	r *http.Request,
) ([]hal.Pageable, error)

GetResourcePage returns a page of offers for a given account.

type GetAccountsHandler 

type GetAccountsHandler struct {
}

GetAccountsHandler is the action handler for the /accounts endpoint

func (GetAccountsHandler) GetResourcePage 

func (handler GetAccountsHandler) GetResourcePage(
	w HeaderWriter,
	r *http.Request,
) ([]hal.Pageable, error)

GetResourcePage returns a page containing the account records that have `signer` as a signer or have a trustline to the given asset.

type GetOfferByID 

type GetOfferByID struct {
}

GetOfferByID is the action handler for the /offers/{id} endpoint

func (GetOfferByID) GetResource 

func (handler GetOfferByID) GetResource(
	w HeaderWriter,
	r *http.Request,
) (hal.Pageable, error)

GetResource returns an offer by id.

type GetOffersHandler 

type GetOffersHandler struct {
}

GetOffersHandler is the action handler for the /offers endpoint

func (GetOffersHandler) GetResourcePage 

func (handler GetOffersHandler) GetResourcePage(
	w HeaderWriter,
	r *http.Request,
) ([]hal.Pageable, error)

GetResourcePage returns a page of offers.

type GetOperationsHandler 

type GetOperationsHandler struct {
	OnlyPayments                bool
	IngestingFailedTransactions bool
}

GetOperationsHandler is the action handler for all end-points returning a list of operations.

func (GetOperationsHandler) GetResourcePage 

func (handler GetOperationsHandler) GetResourcePage(w HeaderWriter, r *http.Request) ([]hal.Pageable, error)

GetResourcePage returns a page of operations.

type GetOrderbookHandler 

type GetOrderbookHandler struct {
}

GetOrderbookHandler is the action handler for the /order_book endpoint

func (GetOrderbookHandler) GetResource 

func (handler GetOrderbookHandler) GetResource(w HeaderWriter, r *http.Request) (StreamableObjectResponse, error)

GetResource implements the /order_book endpoint

type HeaderWriter 

type HeaderWriter interface {
	Header() http.Header
}

HeaderWriter is an interface for setting HTTP response headers

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 MetricsHandler 

type MetricsHandler struct {
	Metrics metrics.Registry
}

MetricsHandler is the action handler for the /metrics endpoint

func (*MetricsHandler) PrometheusFormat 

func (handler *MetricsHandler) PrometheusFormat(w io.Writer) error

PrometheusFormat is a method for actions.PrometheusResponder

type OffersQuery 

type OffersQuery struct {
	SellingBuyingAssetQueryParams `valid:"-"`
	Seller                        string `schema:"seller" valid:"accountID,optional"`
}

OffersQuery query struct for offers end-point

func (OffersQuery) URITemplate 

func (q OffersQuery) URITemplate() string

URITemplate returns a rfc6570 URI template the query struct

func (OffersQuery) Validate 

func (q OffersQuery) Validate() error

Validate runs custom validations.

type OperationsQuery 

type OperationsQuery struct {
	AccountID                 string `schema:"account_id" valid:"accountID,optional"`
	TransactionHash           string `schema:"tx_id" valid:"transactionHash,optional"`
	IncludeFailedTransactions bool   `schema:"include_failed" valid:"-"`
	LedgerID                  uint32 `schema:"ledger_id" valid:"-"`
	Join                      string `schema:"join" valid:"in(transactions)~Accepted values: transactions,optional"`
}

OperationsQuery query struct for offers end-point

func (OperationsQuery) IncludeTransactions 

func (qp OperationsQuery) IncludeTransactions() bool

IncludeTransactions returns extra fields to include in the response

func (OperationsQuery) Validate 

func (qp OperationsQuery) Validate() error

Validate runs extra validations on query parameters

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 OrderBookResponse 

type OrderBookResponse struct {
	protocol.OrderBookSummary
}

OrderBookResponse is the response for the /order_book endpoint OrderBookResponse implements StreamableObjectResponse

func (OrderBookResponse) Equals 

func (o OrderBookResponse) Equals(other StreamableObjectResponse) bool

Equals returns true if the OrderBookResponse is equal to `other`

type PrometheusResponder 

type PrometheusResponder interface {
	PrometheusFormat() error
}

PrometheusResponder implementors can respond to a request whose response type was negotiated to be in a Prometheus simple text-based exposition format.

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 SellingBuyingAssetQueryParams 

type SellingBuyingAssetQueryParams struct {
	SellingAssetType   string `schema:"selling_asset_type" valid:"assetType,optional"`
	SellingAssetIssuer string `schema:"selling_asset_issuer" valid:"accountID,optional"`
	SellingAssetCode   string `schema:"selling_asset_code" valid:"-"`
	BuyingAssetType    string `schema:"buying_asset_type" valid:"assetType,optional"`
	BuyingAssetIssuer  string `schema:"buying_asset_issuer" valid:"accountID,optional"`
	BuyingAssetCode    string `schema:"buying_asset_code" valid:"-"`

	// allow selling and buying using an asset's canonical representation. We
	// are keeping the former selling_* and buying_* for backwards compatibility
	// but it should not be documented.
	SellingAsset string `schema:"selling" valid:"asset,optional"`
	BuyingAsset  string `schema:"buying" valid:"asset,optional"`
}

SellingBuyingAssetQueryParams query struct for end-points requiring a selling and buying asset

func (SellingBuyingAssetQueryParams) Buying 

func (q SellingBuyingAssetQueryParams) Buying() *xdr.Asset

Buying returns an *xdr.Asset representing the buying side of the offer.

func (SellingBuyingAssetQueryParams) Selling 

func (q SellingBuyingAssetQueryParams) Selling() *xdr.Asset

Selling returns an xdr.Asset representing the selling side of the offer.

func (SellingBuyingAssetQueryParams) Validate 

func (q SellingBuyingAssetQueryParams) Validate() error

Validate runs custom validations buying and selling

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.

type StreamableObjectResponse 

type StreamableObjectResponse interface {
	Equals(other StreamableObjectResponse) bool
}

StreamableObjectResponse is an interface for objects returned by streamable object endpoints A streamable object endpoint is an SSE endpoint which returns a single JSON object response instead of a page of items.

type Validateable 

type Validateable interface {
	Validate() error
}

Validateable allow structs to define their own custom validations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.