actions

package
v0.0.0-...-13e2633 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

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

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

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

func (SellingBuyingAssetQueryParams) Selling

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL