peasant

README

Candango Go Peasant

Peasant Protocol: A Contract for Controlling Agents

The Peasant protocol is a high-level abstraction designed to facilitate communication between agents (peasants) and central entities (bastions). It does not impose specific implementation details, security requirements, or redundancy levels, but instead establishes a minimal contract for what must be implemented.

In this protocol, agents are referred to as peasants, while central entities are called bastions. The relationship between a bastion and peasant can be either stateful or stateless. In a stateful scenario, bastions must implement a session control mechanism, requiring peasants to perform "knocks" (similar to knocking on a door) to request permission or establish a valid session. In a stateless scenario, the concept of knocking is ignored.

The Peasant protocol mandates the implementation of nonce generation, consumption and validation on both the peasant and bastion sides. Additionally, bastions must provide a directory list of available resources that peasants can consume.

Support

GoPeasat is one of Candango Open Source Group initiatives. Available under the MIT License.

This site and all documentation are licensed under Creative Commons 3.0.

Copyright © 2023-2025 Flavio Garcia

Documentation

Index

• func BodyAsJson(res *http.Response, jsonBody any) error
• func BodyAsString(res *http.Response) (string, error)
• func NonceServed(s NonceService, key string) func(http.Handler) http.Handler
• func Nonced(next http.Handler, s NonceService) http.Handler
• func NoncedHandlerFunc(s NonceService, f func(http.ResponseWriter, *http.Request)) func(http.ResponseWriter, *http.Request)
• type DirectoryProvider
• type HttpDirectoryProvider
  • func NewHttpDirectoryProvider(url string) *HttpDirectoryProvider
  • func (p *HttpDirectoryProvider) Directory() (map[string]any, error)
  • func (p *HttpDirectoryProvider) GetUrl() string
  • func (p *HttpDirectoryProvider) SetTransport(t Transport) error
• type HttpTransport
  • func NewHttpTransport(p DirectoryProvider) (*HttpTransport, error)
  • func (ht *HttpTransport) NewNonce() (string, error)
  • func (ht *HttpTransport) NewNonceUrl() (string, error)
  • func (ht *HttpTransport) ResolveNonce(res *http.Response) string
• type MemoryDirectoryProvider
  • func (p *MemoryDirectoryProvider) Directory() (map[string]any, error)
  • func (p *MemoryDirectoryProvider) GetUrl() string
  • func (p *MemoryDirectoryProvider) SetTransport(_ Transport) error
• type NonceService
• type Peasant
  • func NewPeasant(tr Transport) *Peasant
  • func (p *Peasant) NewNonce() (string, error)
• type Transport

Functions

func BodyAsJson

func BodyAsJson(res *http.Response, jsonBody any) error

BodyAsJson reads the entire body of an HTTP response and unmarshals it into the provided jsonBody. It consumes the response body, so the caller should not attempt to read from it again. The jsonBody parameter should be a pointer to a struct or a slice where JSON data will be unmarshaled.

func BodyAsString

func BodyAsString(res *http.Response) (string, error)

BodyAsString reads the entire body of an HTTP response and returns it as a string. It consumes the response body, so the caller should not attempt to read from it again.

func NonceServed

func NonceServed(s NonceService, key string) func(http.Handler) http.Handler

NonceServed creates a middleware that injects a NonceService into the request's context.

func Nonced

func Nonced(next http.Handler, s NonceService) http.Handler

Nonced is a middleware that verifies the presence of a valid nonce in a request. If the nonce is not provided or is invalid, it prevents the request from proceeding.

func NoncedHandlerFunc

func NoncedHandlerFunc(
	s NonceService, f func(http.ResponseWriter, *http.Request),
) func(http.ResponseWriter, *http.Request)

Types

type DirectoryProvider

type DirectoryProvider interface {
	// Directory fetches the directory map from the provider.
	Directory() (map[string]any, error)
	// GetUrl returns the provider's URL.
	GetUrl() string
	// SetTransport sets the transport mechanism for the provider.
	SetTransport(Transport) error
}

DirectoryProvider defines the interface for objects that provide directory information. Implementations should support retrieving a directory map, getting the URL, and setting the transport.

type HttpDirectoryProvider

type HttpDirectoryProvider struct {
	Url string
	*HttpTransport
}

HttpDirectoryProvider provides access to a remote directory via HTTP. It uses an embedded HttpTransport to make requests to the given URL.

func NewHttpDirectoryProvider

func NewHttpDirectoryProvider(url string) *HttpDirectoryProvider

NewHttpDirectoryProvider creates and returns a new HttpDirectoryProvider with the given URL.

func (*HttpDirectoryProvider) Directory

func (p *HttpDirectoryProvider) Directory() (map[string]any, error)

Directory fetches the remote directory from the provider's URL. It returns a map representing the directory, or an error if the request or decoding fails.

func (*HttpDirectoryProvider) GetUrl

func (p *HttpDirectoryProvider) GetUrl() string

GetUrl returns the URL configured for the HTTP directory provider.

func (*HttpDirectoryProvider) SetTransport

func (p *HttpDirectoryProvider) SetTransport(t Transport) error

SetTransport sets the HTTP transport for the provider. It attempts to cast the given Transport to *HttpTransport. Returns an error if the cast fails.

type HttpTransport

type HttpTransport struct {
	// DirectoryProvider is embedded to provide directory-related functionality.
	DirectoryProvider
	// DirectoryKey is the key used to retrieve the directory-related url.
	DirectoryKey string
	// DirectoryMethod specifies the HTTP method used for directory operations.
	DirectoryMethod string
	// Client is the HTTP Client used for making requests.
	http.Client
	// NonceKey is the header key used to retrieve the nonce from responses.
	NonceKey string
}

HttpTransport implements the Transport interface for HTTP communications.

func NewHttpTransport

func NewHttpTransport(p DirectoryProvider) (*HttpTransport, error)

NewHttpTransport initializes and returns a new HttpTransport using the provided DirectoryProvider. It sets up the transport in the provider and returns the configured HttpTransport. Returns an error if setting the transport fails.

func (*HttpTransport) NewNonce

func (ht *HttpTransport) NewNonce() (string, error)

NewNonce generates a new nonce by making an HTTP HEAD request to the new nonce URL. This method depends on NewNonceUrl and ResolveNonce. The basic implementation is provided, but customization should be done in the dependent methods. If further customization is needed, developers can use this method as a template.

func (*HttpTransport) NewNonceUrl

func (ht *HttpTransport) NewNonceUrl() (string, error)

NewNonceUrl returns the URL for generating a new nonce. Developers should override this method if the new nonce URL needs to be resolved differently.

func (*HttpTransport) ResolveNonce

func (ht *HttpTransport) ResolveNonce(res *http.Response) string

ResolveNonce extracts the nonce from the response headers using the predefined nonceKey. Developers should override this method if the nonce needs to be resolved in a different way.

type MemoryDirectoryProvider

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

MemoryDirectoryProvider is an in-memory implementation of DirectoryProvider. It holds a URL and returns predefined directory data.

func (*MemoryDirectoryProvider) Directory

func (p *MemoryDirectoryProvider) Directory() (map[string]any, error)

Directory returns a static map containing the directory endpoints. It constructs the "newNonce" endpoint using the provider's URL.

func (*MemoryDirectoryProvider) GetUrl

func (p *MemoryDirectoryProvider) GetUrl() string

GetUrl returns the URL configured for the memory provider.

func (*MemoryDirectoryProvider) SetTransport

func (p *MemoryDirectoryProvider) SetTransport(_ Transport) error

SetTransport is a no-op for MemoryDirectoryProvider, as it does not use a transport. It always returns nil.

type NonceService

type NonceService interface {

	// Block blocks the provided HTTP request if the nonce is not valid.
	Block(http.ResponseWriter, *http.Request) error

	// Clear clears a nonce associated with the specified key. If the key
	// doesn't exists no error will be returned.
	//
	// Return errors only if an actual error occours.
	Clear(string) error

	// Consume processes the nonce associated with the specified key and
	// returns a boolean indicating whether the nonce was successfully
	// consumed, along with any error encountered.
	// If nonce connot be consumed header sould be set with the respective http
	// error code.
	Consume(http.ResponseWriter, *http.Request) error

	// GetNonce generates a new nonce, and stores it for a future validation.
	// It returns the nonce as a string and an error if any occurred during
	// the nonce generation or header update.
	GetNonce(*http.Request) (string, error)

	// Skip return if the request should be nonced or not.
	Skip(*http.Request) bool

	// Provided verifies the presence of a valid nonce in the specified HTTP
	// request.
	//
	// If the nonce is not provided or is invalid, it sets the response HTTP
	// status to "Unauthorized", "Forbidden", or another appropriate status
	// based on the specific conditions and checks performed within the method.
	// If nonce is not provided header sould be set with the respective http
	// error code.
	Provided(http.ResponseWriter, *http.Request) error
}

NonceService defines methods for managing nonces in HTTP requests. It provides functionality for blocking, clearing, consuming, getting, and checking the provision of nonces.

type Peasant

type Peasant struct {
	Transport
}

Peasant represents an agent in the Peasant protocol, which communicates with a bastion. It wraps a Transport for handling nonce generation and other communication aspects.

func NewPeasant

func NewPeasant(tr Transport) *Peasant

NewPeasant initializes a new Peasant with the provided Transport.

func (*Peasant) NewNonce

func (p *Peasant) NewNonce() (string, error)

NewNonce generates a new nonce by delegating the call to the underlying Transport. This method allows the Peasant to obtain a new nonce for communication with a bastion.

type Transport

type Transport interface {
	// NewNonce generates a new nonce.
	NewNonce() (string, error)
	// Directory returns the directory map.
	Directory() (map[string]any, error)
}

Transport defines the interface for handling nonce generation and directory listing.