http

package
v8.24.2 Latest Latest
Warning

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

 Go to latest Published: May 4, 2024 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package http provides the HTTP server for accessing the distributed database.

Index

Constants

View Source 
const (

	// VersionHTTPHeader is the HTTP header key for the version.
	VersionHTTPHeader = "X-RQLITE-VERSION"

	// ServedByHTTPHeader is the HTTP header used to report which
	// node (by node Raft address) actually served the request if
	// it wasn't served by this node.
	ServedByHTTPHeader = "X-RQLITE-SERVED-BY"

	// AllowOriginHeader is the HTTP header for allowing CORS compliant access from certain origins
	AllowOriginHeader = "Access-Control-Allow-Origin"

	// AllowMethodsHeader is the HTTP header for supporting the correct methods
	AllowMethodsHeader = "Access-Control-Allow-Methods"

	// AllowHeadersHeader is the HTTP header for supporting the correct request headers
	AllowHeadersHeader = "Access-Control-Allow-Headers"

	// AllowCredentialsHeader is the HTTP header for supporting specifying credentials
	AllowCredentialsHeader = "Access-Control-Allow-Credentials"
)

Variables

View Source 
var (
	// ErrNoStatements is returned when a request is empty
	ErrNoStatements = errors.New("no statements")

	// ErrInvalidJSON is returned when a body is not valid JSON
	ErrInvalidJSON = errors.New("invalid JSON body")

	// ErrInvalidRequest is returned when a request cannot be parsed.
	ErrInvalidRequest = errors.New("invalid request")

	// ErrUnsupportedType is returned when a request contains an unsupported type.
	ErrUnsupportedType = errors.New("unsupported type")
)
View Source 
var (
	// ErrLeaderNotFound is returned when a node cannot locate a leader
	ErrLeaderNotFound = errors.New("leader not found")
)

Functions

func AnyServingHTTP added in v8.13.5 

func AnyServingHTTP(addrs []string) (string, bool)

AnyServingHTTP returns the first address in the list that appears to be serving HTTP or HTTPS, or false if none of them are.

func IsServingHTTP 

func IsServingHTTP(addr string) bool

IsServingHTTP returns true if there appears to be a HTTP or HTTPS server running on the given address.

func ParseRequest 

func ParseRequest(b []byte) ([]*command.Statement, error)

ParseRequest generates a set of Statements for a given byte slice.

func ResetStats 

func ResetStats()

ResetStats resets the expvar stats for this module. Mostly for test purposes.

Types

type Cluster 

type Cluster interface {
	GetAddresser

	// Execute performs an Execute Request on a remote node.
	Execute(er *proto.ExecuteRequest, nodeAddr string, creds *clstrPB.Credentials, timeout time.Duration, retries int) ([]*proto.ExecuteQueryResponse, error)

	// Query performs an Query Request on a remote node.
	Query(qr *proto.QueryRequest, nodeAddr string, creds *clstrPB.Credentials, timeout time.Duration) ([]*proto.QueryRows, error)

	// Request performs an ExecuteQuery Request on a remote node.
	Request(eqr *proto.ExecuteQueryRequest, nodeAddr string, creds *clstrPB.Credentials, timeout time.Duration, retries int) ([]*proto.ExecuteQueryResponse, error)

	// Backup retrieves a backup from a remote node and writes to the io.Writer.
	Backup(br *proto.BackupRequest, nodeAddr string, creds *clstrPB.Credentials, timeout time.Duration, w io.Writer) error

	// Load loads a SQLite database into the node.
	Load(lr *proto.LoadRequest, nodeAddr string, creds *clstrPB.Credentials, timeout time.Duration, retries int) error

	// RemoveNode removes a node from the cluster.
	RemoveNode(rn *proto.RemoveNodeRequest, nodeAddr string, creds *clstrPB.Credentials, timeout time.Duration) error

	// Stats returns stats on the Cluster.
	Stats() (map[string]interface{}, error)
}

Cluster is the interface node API services must provide

type CredentialStore 

type CredentialStore interface {
	// AA authenticates and checks authorization for the given perm.
	AA(username, password, perm string) bool
}

CredentialStore is the interface credential stores must support.

type DBResults 

type DBResults struct {
	ExecuteQueryResponse []*proto.ExecuteQueryResponse
	QueryRows            []*proto.QueryRows

	AssociativeJSON bool // Render in associative form
	BlobsAsArrays   bool // Render BLOB data as byte arrays
}

DBResults stores either an Execute result, a Query result, or an ExecuteQuery result.

func (*DBResults) MarshalJSON 

func (d *DBResults) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON Marshaler interface.

type Database 

type Database interface {
	// Execute executes a slice of queries, each of which is not expected
	// to return rows. If timings is true, then timing information will
	// be return. If tx is true, then either all queries will be executed
	// successfully or it will as though none executed.
	Execute(er *proto.ExecuteRequest) ([]*proto.ExecuteQueryResponse, error)

	// Query executes a slice of queries, each of which returns rows. If
	// timings is true, then timing information will be returned. If tx
	// is true, then all queries will take place while a read transaction
	// is held on the database.
	Query(qr *proto.QueryRequest) ([]*proto.QueryRows, error)

	// Request processes a slice of requests, each of which can be either
	// an Execute or Query request.
	Request(eqr *proto.ExecuteQueryRequest) ([]*proto.ExecuteQueryResponse, error)

	// Load loads a SQLite file into the system via Raft consensus.
	Load(lr *proto.LoadRequest) error
}

Database is the interface any queryable system must implement

type GetAddresser 

type GetAddresser interface {
	GetNodeAPIAddr(addr string, retries int, timeout time.Duration) (string, error)
}

GetAddresser is the interface that wraps the GetNodeAPIAddr method. GetNodeAPIAddr returns the HTTP API URL for the node at the given Raft address.

type Node 

type Node struct {
	ID        string  `json:"id,omitempty"`
	APIAddr   string  `json:"api_addr,omitempty"`
	Addr      string  `json:"addr,omitempty"`
	Voter     bool    `json:"voter"`
	Reachable bool    `json:"reachable"`
	Leader    bool    `json:"leader"`
	Time      float64 `json:"time,omitempty"`
	TimeS     string  `json:"time_s,omitempty"`
	Error     string  `json:"error,omitempty"`
	// contains filtered or unexported fields
}

Node represents a single node in the cluster and can include information about the node's reachability and leadership status. If there was an error communicating with the node, the Error field will be populated.

func NewNodeFromServer 

func NewNodeFromServer(s *store.Server) *Node

NewNodeFromServer creates a Node from a Server.

func (*Node) MarshalJSON 

func (n *Node) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Node) SetError 

func (n *Node) SetError(err string)

SetError sets the Error field of the Node in a synchronized manner.

func (*Node) Test 

func (n *Node) Test(ga GetAddresser, leaderAddr string, retries int, timeout time.Duration)

Test tests the node's reachability and leadership status. If an error occurs, the Error field will be populated.

type Nodes 

type Nodes []*Node

func NewNodesFromServers 

func NewNodesFromServers(servers []*store.Server) Nodes

NewNodesFromServers creates a slice of Nodes from a slice of Servers.

func (Nodes) GetNode 

func (n Nodes) GetNode(id string) *Node

GetNode returns the Node with the given ID, or nil if no such node exists.

func (Nodes) HasAddr 

func (n Nodes) HasAddr(addr string) bool

HasAddr returns whether any node in the Nodes slice has the given Raft address.

func (Nodes) Len 

func (n Nodes) Len() int

func (Nodes) Less 

func (n Nodes) Less(i, j int) bool

func (Nodes) Swap 

func (n Nodes) Swap(i, j int)

func (Nodes) Test 

func (n Nodes) Test(ga GetAddresser, leaderAddr string, retries int, timeout time.Duration)

Test tests the reachability and leadership status of all nodes. It does this in parallel, and blocks until all nodes have been tested.

func (Nodes) Voters 

func (n Nodes) Voters() Nodes

Voters returns a slice of Nodes that are voters.

type NodesRespDecoder 

type NodesRespDecoder struct {
	// contains filtered or unexported fields
}

NodesRespDecoder decodes JSON data into a slice of Nodes.

func NewNodesRespDecoder 

func NewNodesRespDecoder(r io.Reader) *NodesRespDecoder

NewNodesRespDecoder creates a new Decoder instance with the specified io.Reader.

func (*NodesRespDecoder) Decode 

func (d *NodesRespDecoder) Decode(nodes *Nodes) error

Decode reads JSON from its reader and decodes it into the provided Nodes slice.

type NodesRespEncoder 

type NodesRespEncoder struct {
	// contains filtered or unexported fields
}

NodesRespEncoder encodes Nodes into JSON with an option for legacy format.

func NewNodesRespEncoder 

func NewNodesRespEncoder(w io.Writer, legacy bool) *NodesRespEncoder

NewNodesRespEncoder creates a new NodesRespEncoder instance with the specified io.Writer and legacy flag.

func (*NodesRespEncoder) Encode 

func (e *NodesRespEncoder) Encode(nodes Nodes) error

Encode takes a slice of Nodes and encodes it into JSON, writing the output to the Encoder's writer.

func (*NodesRespEncoder) SetIndent 

func (e *NodesRespEncoder) SetIndent(prefix, indent string)

SetIndent sets the indentation format for the JSON output.

type QueryParams 

type QueryParams map[string]string

QueryParams represents the query parameters passed in an HTTP request. Query parameter keys are case-sensitive, as per the HTTP spec.

func NewQueryParams 

func NewQueryParams(r *http.Request) (QueryParams, error)

NewQueryParams returns a new QueryParams from the given HTTP request.

func (QueryParams) Associative 

func (qp QueryParams) Associative() bool

Associative returns true if the query parameters request associative results.

func (QueryParams) BackupFormat 

func (qp QueryParams) BackupFormat() command.BackupRequest_Format

BackupFormat returns the requested backup format.

func (QueryParams) BlobArray added in v8.22.0 

func (qp QueryParams) BlobArray() bool

BlobArray returns true if the query parameters request BLOB array results.

func (QueryParams) Bypass 

func (qp QueryParams) Bypass() bool

Bypass returns true if the query parameters indicate bypass mode.

func (QueryParams) Compress added in v8.16.0 

func (qp QueryParams) Compress() bool

Compress returns true if the query parameters request compression.

func (QueryParams) DBTimeout added in v8.19.0 

func (qp QueryParams) DBTimeout(def time.Duration) time.Duration

DBTimeout returns the value of the key named "db_timeout".

func (QueryParams) Freshness 

func (qp QueryParams) Freshness() time.Duration

Freshness returns the requested freshness duration.

func (QueryParams) FreshnessStrict added in v8.20.0 

func (qp QueryParams) FreshnessStrict() bool

FreshnessStrict returns true if the query parameters indicate strict freshness.

func (QueryParams) HasKey 

func (qp QueryParams) HasKey(k string) bool

HasKey returns true if the given key is present in the query parameters.

func (QueryParams) Key 

func (qp QueryParams) Key() string

Key returns the value of the key named "key".

func (QueryParams) Level 

func (qp QueryParams) Level() command.QueryRequest_Level

Level returns the requested consistency level.

func (QueryParams) NoLeader 

func (qp QueryParams) NoLeader() bool

NoLeader returns true if the query parameters request no leader mode.

func (QueryParams) NoParse added in v8.23.0 

func (qp QueryParams) NoParse() bool

NoParse returns true if the query parameters indicate no SQL parsing should be performed.

func (QueryParams) NoRewriteRandom 

func (qp QueryParams) NoRewriteRandom() bool

NoRewrite returns true if the query parameters request no rewriting of queries.

func (QueryParams) NonVoters 

func (qp QueryParams) NonVoters() bool

NonVoters returns true if the query parameters request non-voters to be included in results.

func (QueryParams) Pretty 

func (qp QueryParams) Pretty() bool

Pretty returns true if the query parameters indicate pretty-printing should be returned.

func (QueryParams) Query 

func (qp QueryParams) Query() string

Query returns the requested query.

func (QueryParams) Queue 

func (qp QueryParams) Queue() bool

Queue returns true if the query parameters request queued operation

func (QueryParams) Redirect 

func (qp QueryParams) Redirect() bool

Redirect returns true if the query parameters request redirect mode.

func (QueryParams) Retries added in v8.18.0 

func (qp QueryParams) Retries(def int) int

Retries returns the requested number of retries.

func (QueryParams) Sync added in v8.21.0 

func (qp QueryParams) Sync() bool

Sync returns whether the sync flag is set.

func (QueryParams) Timeout 

func (qp QueryParams) Timeout(def time.Duration) time.Duration

Timeout returns the requested timeout duration.

func (QueryParams) Timings 

func (qp QueryParams) Timings() bool

Timings returns true if the query parameters indicate timings should be returned.

func (QueryParams) Tx 

func (qp QueryParams) Tx() bool

Tx returns true if the query parameters indicate the query should be executed in a transaction.

func (QueryParams) Vacuum 

func (qp QueryParams) Vacuum() bool

Vacuum returns true if the query parameters request vacuum mode.

func (QueryParams) Version 

func (qp QueryParams) Version() string

Version returns the requested version.

func (QueryParams) Wait 

func (qp QueryParams) Wait() bool

Wait returns true if the query parameters indicate the query should wait.

type Response 

type Response struct {
	Results     *DBResults `json:"results,omitempty"`
	Error       string     `json:"error,omitempty"`
	Time        float64    `json:"time,omitempty"`
	SequenceNum int64      `json:"sequence_number,omitempty"`
	// contains filtered or unexported fields
}

Response represents a response from the HTTP service.

func NewResponse 

func NewResponse() *Response

NewResponse returns a new instance of response.

func (*Response) SetTime 

func (r *Response) SetTime()

SetTime sets the Time attribute of the response. This way it will be present in the serialized JSON version.

type Responser 

type Responser interface {
	SetTime()
}

Responser is the interface response objects must implement.

type ResultsError 

type ResultsError interface {
	Error() string
	IsAuthorized() bool
}

type Service 

type Service struct {
	CACertFile   string // Path to x509 CA certificate used to verify certificates.
	CertFile     string // Path to server's own x509 certificate.
	KeyFile      string // Path to server's own x509 private key.
	ClientVerify bool   // Whether client certificates should verified.

	DefaultQueueCap     int
	DefaultQueueBatchSz int
	DefaultQueueTimeout time.Duration
	DefaultQueueTx      bool

	BuildInfo map[string]interface{}
	// contains filtered or unexported fields
}

Service provides HTTP service.

func New 

func New(addr string, store Store, cluster Cluster, credentials CredentialStore) *Service

New returns an uninitialized HTTP service. If credentials is nil, then the service performs no authentication and authorization checks.

func (*Service) Addr 

func (s *Service) Addr() net.Addr

Addr returns the address on which the Service is listening

func (*Service) AllowOrigin 

func (s *Service) AllowOrigin() string

AllowOrigin returns the value for the Access-Control-Allow-Origin header.

func (*Service) CheckRequestPerm 

func (s *Service) CheckRequestPerm(r *http.Request, perm string) (b bool)

CheckRequestPerm checks if the request is authenticated and authorized with the given Perm.

func (*Service) CheckRequestPermAll 

func (s *Service) CheckRequestPermAll(r *http.Request, perms ...string) (b bool)

CheckRequestPermAll checks if the request is authenticated and authorized with all the given Perms.

func (*Service) Close 

func (s *Service) Close()

Close closes the service.

func (*Service) DoRedirect 

func (s *Service) DoRedirect(w http.ResponseWriter, r *http.Request, qp QueryParams) bool

DoRedirect checks if the request is a redirect, and if so, performs the redirect. Returns true caller can consider the request handled. Returns false if the request was not a redirect and the caller should continue processing the request.

func (*Service) FormRedirect 

func (s *Service) FormRedirect(r *http.Request) (string, error)

FormRedirect returns the value for the "Location" header for a 301 response.

func (*Service) HTTPS 

func (s *Service) HTTPS() bool

HTTPS returns whether this service is using HTTPS.

func (*Service) LeaderAPIAddr 

func (s *Service) LeaderAPIAddr() string

LeaderAPIAddr returns the API address of the leader, as known by this node.

func (*Service) RegisterStatus 

func (s *Service) RegisterStatus(key string, stat StatusReporter) error

RegisterStatus allows other modules to register status for serving over HTTP.

func (*Service) ServeHTTP 

func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP allows Service to serve HTTP requests.

func (*Service) SetAllowOrigin added in v8.24.0 

func (s *Service) SetAllowOrigin(origin string)

SetAllowOrigin sets the value for the Access-Control-Allow-Origin header.

func (*Service) Start 

func (s *Service) Start() error

Start starts the service.

type StatusReporter 

type StatusReporter interface {
	Stats() (map[string]interface{}, error)
}

StatusReporter is the interface status providers must implement.

type Store 

type Store interface {
	Database

	// Remove removes the node from the cluster.
	Remove(rn *proto.RemoveNodeRequest) error

	// LeaderAddr returns the Raft address of the leader of the cluster.
	LeaderAddr() (string, error)

	// Ready returns whether the Store is ready to service requests.
	Ready() bool

	// Committed blocks until the local commit index is greater than or
	// equal to the Leader index, as checked when the function is called.
	Committed(timeout time.Duration) (uint64, error)

	// Stats returns stats on the Store.
	Stats() (map[string]interface{}, error)

	// Nodes returns the slice of store.Servers in the cluster
	Nodes() ([]*store.Server, error)

	// Backup writes backup of the node state to dst
	Backup(br *proto.BackupRequest, dst io.Writer) error

	// ReadFrom reads and loads a SQLite database into the node, initially bypassing
	// the Raft system. It then triggers a Raft snapshot, which will then make
	// Raft aware of the new data.
	ReadFrom(r io.Reader) (int64, error)
}

Store is the interface the Raft-based database must implement.

Source Files

View all Source files

Directories

Path Synopsis

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.