api

Documentation

Overview

Package api describes the JSON data structures for v1 requests and responses. It is stored in its own package to facilitate ease of serialization for Go API clients and to describe and document the API for external users.

Index

• type APIv1
  • func (s APIv1) CreateSecret(ctx context.Context, in *CreateSecretRequest) (out *CreateSecretReply, err error)
  • func (s APIv1) DestroySecret(ctx context.Context, token, password string) (out *DestroySecretReply, err error)
  • func (s APIv1) Do(req *http.Request, data interface{}, checkStatus bool) (rep *http.Response, err error)
  • func (s APIv1) FetchSecret(ctx context.Context, token, password string) (out *FetchSecretReply, err error)
  • func (s APIv1) NewRequest(ctx context.Context, method, path string, data interface{}) (req *http.Request, err error)
  • func (s APIv1) Status(ctx context.Context) (out *StatusReply, err error)
• type CreateSecretReply
• type CreateSecretRequest
• type DestroySecretReply
• type Duration
  • func (d Duration) MarshalJSON() ([]byte, error)
  • func (d *Duration) UnmarshalJSON(b []byte) error
• type FetchSecretReply
• type Reply
• type Service
  • func New(endpoint string) (_ Service, err error)
• type StatusReply

Types

type APIv1

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

APIv1 implements the Service interface. TODO: add redirect check that ensures the client only accesses v1 routes.

func (APIv1) CreateSecret

func (s APIv1) CreateSecret(ctx context.Context, in *CreateSecretRequest) (out *CreateSecretReply, err error)

func (APIv1) DestroySecret

func (s APIv1) DestroySecret(ctx context.Context, token, password string) (out *DestroySecretReply, err error)

func (APIv1) Do

func (s APIv1) Do(req *http.Request, data interface{}, checkStatus bool) (rep *http.Response, err error)

Do executes an http request against the server, performs error checking, and deserializes the response data into the specified struct if requested.

func (APIv1) FetchSecret

func (s APIv1) FetchSecret(ctx context.Context, token, password string) (out *FetchSecretReply, err error)

func (APIv1) NewRequest

func (s APIv1) NewRequest(ctx context.Context, method, path string, data interface{}) (req *http.Request, err error)

NewRequest creates an http.Request with the specified context and method, resolving the path to the root endpoint of the API (e.g. /v1) and serializes the data to JSON. This method also sets the default headers of all whisper client requests.

func (APIv1) Status

func (s APIv1) Status(ctx context.Context) (out *StatusReply, err error)

type CreateSecretReply

type CreateSecretReply struct {
	Token   string    `json:"token"`   // the token used to retrieve the secret (so the URL doesn't have to be parsed)
	Expires time.Time `json:"expires"` // the timestamp when the secret will have expired
}

type CreateSecretRequest

type CreateSecretRequest struct {
	Secret   string   `json:"secret" binding:"required"` // the secret can be a string of any length or base64 encoded data
	Password string   `json:"password,omitempty"`        // a password that must be used to retrieve the secret
	Accesses int      `json:"accesses,omitempty"`        // specify the number of times the secret can be accessed; default is 1, if negative, can be accessed until the secret expires
	Lifetime Duration `json:"lifetime,omitempty"`        // how long the secret will last before being deleted
	Filename string   `json:"filename,omitempty"`        // if the secret is a filename, the name of the file
	IsBase64 bool     `json:"is_base64"`                 // if the secret is base64 encoded or not
}

type DestroySecretReply

type DestroySecretReply struct {
	Destroyed bool `json:"destroyed"` // if the secret was destroyed or not
}

type Duration

type Duration time.Duration

Duration implements a JSON serializable time.Duration.

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON the duration as a string, e.g. 10s

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON from either a float64 or a string

type FetchSecretReply

type FetchSecretReply struct {
	Secret    string    `json:"secret"`             // the secret retrieved by the database, which is now deleted
	Filename  string    `json:"filename,omitempty"` // the name of the file used to create the secret to save as a file
	IsBase64  bool      `json:"is_base64"`          // if the secret is base64 encoded data
	Created   time.Time `json:"created"`            // the timestamp the secret was created
	Accesses  int       `json:"accesses"`           // the number of times the secret has been accessed
	Destroyed bool      `json:"destroyed"`          // if the secret was destroyed after the fetch
}

type Reply

type Reply struct {
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty" yaml:"error,omitempty"`
}

Reply contains standard fields that are embedded in most API responses

type Service

type Service interface {
	Status(ctx context.Context) (out *StatusReply, err error)
	CreateSecret(ctx context.Context, in *CreateSecretRequest) (out *CreateSecretReply, err error)
	FetchSecret(ctx context.Context, token, password string) (out *FetchSecretReply, err error)
	DestroySecret(ctx context.Context, token, password string) (out *DestroySecretReply, err error)
}

Service defines the API, which is implemented by the v1 client.

func New

func New(endpoint string) (_ Service, err error)

type StatusReply

type StatusReply struct {
	Status  string `json:"status"`
	Uptime  string `json:"uptime,omitempty"`
	Version string `json:"version,omitempty"`
	Error   string `json:"error,omitempty" yaml:"error,omitempty"`
}

StatusReply is returned on status requests. Note that no request is needed.