federation

Documentation

Overview

Package federation provides a pluggable handler that satisfies the Payshares federation protocol. Add an instance of `Handler` onto your router to allow a server to satisfy the protocol.

The central type in this package is the "Driver" interfaces. Implementing these interfaces allows a developer to plug in their own back end, whether it be a RDBMS, a KV store, or even just an in memory data structure.

A pre-baked implementation of `Driver` and `ReverseDriver` that provides simple access to SQL systems is included. See `SQLDriver` for more details.

Index

• type Driver
• type ErrorResponse
• type ForwardDriver
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Record
• type ReverseDriver
• type ReverseRecord
• type ReverseSQLDriver
  • func (drv *ReverseSQLDriver) LookupReverseRecord(accountid string) (*ReverseRecord, error)
• type SQLDriver
  • func (drv *SQLDriver) LookupRecord(name, domain string) (*Record, error)

Types

type Driver

type Driver interface {
	// LookupRecord is called when a handler receives a so-called "name"
	// federation request to lookup a `Record` using the provided payshares address.
	// An implementation should return a nil `*Record` value if the lookup
	// successfully executed but no result was found.
	LookupRecord(name string, domain string) (*Record, error)
}

Driver represents a data source against which federation queries can be executed.

type ErrorResponse

type ErrorResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorResponse represents the JSON response sent to a client when the request triggered an error.

type ForwardDriver

type ForwardDriver interface {
	// Forward is called when a handler receives a so-called "forward"
	// federation request to lookup a `Record` using the provided data (ex. bank
	// account number).
	// An implementation should return a nil `*Record` value if the lookup
	// successfully executed but no result was found.
	LookupForwardingRecord(query url.Values) (*Record, error)
}

ForwardDriver represents a data source against which forward queries can be executed.

type Handler

type Handler struct {
	// Driver is the backend against which queries will be evaluated.
	Driver Driver
}

Handler represents an http handler that can service http requests that conform to the Payshares federation protocol. This handler should be added to your chosen mux at the path `/federation` (and for good measure `/federation/` if your middleware doesn't normalize trailing slashes).

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Record

type Record struct {
	AccountID string `db:"id"`
	MemoType  string `db:"memo_type"`
	Memo      string `db:"memo"`
}

Record represents the result from the database when performing a federation request.

type ReverseDriver

type ReverseDriver interface {
	// LookupReverseRecord is called when a handler receives a "reverse"
	// federation request to lookup a `ReverseRecord` using the provided psrkey
	// encoded accountID. An implementation should return a nil `*ReverseRecord`
	// value if the lookup successfully executed but no result was found.
	LookupReverseRecord(accountID string) (*ReverseRecord, error)
}

ReverseDriver represents a data source against which federation queries can be executed.

type ReverseRecord

type ReverseRecord struct {
	Name   string `db:"name"`
	Domain string `db:"domain"`
}

ReverseRecord represents the result from performing a "Reverse federation" lookup, in which an Account ID is used to lookup an associated address.

type ReverseSQLDriver

type ReverseSQLDriver struct {
	SQLDriver

	// LookupReverseRecordQuery is a SQL query used for performing "reverse"
	// federation queries.  This query should accomodate a single parameter, using
	// "?" as the placeholder.  This provided parameter will be a psrkey-encoded
	// payshares account id to lookup, such as
	// "GDOP3VI4UA5LS7AMLJI66RJUXEQ4HX46WUXTRTJGI5IKDLNWUBOW3FUK".
	LookupReverseRecordQuery string
}

ReverseSQLDriver provides a `ReverseDriver` implementation based upon a SQL Server. See `SQLDriver`, the forward only version, for more details.

func (*ReverseSQLDriver) LookupReverseRecord

func (drv *ReverseSQLDriver) LookupReverseRecord(
	accountid string,
) (*ReverseRecord, error)

LookupReverseRecord implements `ReverseDriver` by performing `drv.LookupReverseRecordQuery` against `drv.DB` using the provided parameter

type SQLDriver

type SQLDriver struct {
	// DB is the target database that federation queries will be executed against
	DB *sql.DB

	// Dialect is the type of database peer field `DB` is communicating with.  It
	// is equivalent to the `driverName` params used in a call to `sql.Open` from
	// the standard library.
	Dialect string

	// LookupRecordQuery is a SQL query used for performing "forward" federation
	// queries.  This query should accomodate one or two parameters, using "?" as
	// the placeholder.  This provided parameters will be a name and domain
	LookupRecordQuery string
	// contains filtered or unexported fields
}

SQLDriver represents an implementation of `Driver` that provides a simple way to incorporate a SQL-backed federation handler into an application. Note: this type is not designed for dynamic configuration changes. Once a method is called on the struct the public fields of this struct should be considered frozen.

func (*SQLDriver) LookupRecord

func (drv *SQLDriver) LookupRecord(name, domain string) (*Record, error)

LookupRecord implements `Driver` by performing `drv.LookupRecordQuery` against `drv.DB` using the provided parameters