api

Documentation

Index

• Variables
• func CreateRecipe(name string, contents *[]byte) error
• func DeleteRecipe(name string) error
• func EncodeJWTToString(token JWT) string
• func GenerateJWTJSON(username string, ttl int64) ([]byte, error)
• func GetAllRecipeNames() ([]string, error)
• func GetAllRecipeNamesJSON() ([]byte, error)
• func GetRecipeJSON(name string) ([]byte, error)
• func GetRecipeNamesPagedJSON(n uint64, size uint64) ([]byte, error)
• func GetRecipeSource(name string) ([]byte, error)
• func RenameRecipe(name string, target string) error
• func SearchRecipeNames(query string) ([]string, error)
• func SearchRecipeNamesJSON(query string) ([]byte, error)
• func SearchRecipeNamesPagedJSON(query string, n uint64, count uint64) ([]byte, error)
• func UpdateRecipe(name string, contents *[]byte) error
• func ValidateJWT(token JWT) error
• func ValidateJWTJSON(jsonBytes []byte) error
• type JWT
  • func DecodeJWTFromJSON(jsonBytes []byte) (JWT, error)
  • func GenerateJWT(username string, issued int64, expiry int64) (JWT, error)
• type JWTHeader
• type JWTPayload

Variables

var (
	ErrJWTMalformed   = errors.New("Malformed JWT Json.")
	ErrJWTFutureDated = errors.New("JWT issue time is in the future.")
	ErrJWTExpired     = errors.New("JWT is expired.")
	ErrJWTMismatch    = errors.New("JWT signature mismatch.")
)

Functions

func CreateRecipe

func CreateRecipe(name string, contents *[]byte) error

Creates a *new* recipe using the provided relative filepath.

e.g. "breakfast/eggs_benedict"

Considerations:
- Returns nil on success, forwards error on failure
- Overwrites will return an error
- This can only create `.cook` files *within* the recipe directory.

func DeleteRecipe

func DeleteRecipe(name string) error

Deletes a recipe based on its relative file path from the recipe root folder as defined in the config file.

e.g. "breakfast/eggs_benedict"

	Considerations:
	- Returns nil on success, forwards error on failure
	- This can only delete `.cook` files *within* the recipe directory.
 	- Deletes empty parent directories (automatic housekeeping)

func EncodeJWTToString

func EncodeJWTToString(token JWT) string

Encodes a `JWT` struct as a standard JWT string

func GenerateJWTJSON

func GenerateJWTJSON(username string, ttl int64) ([]byte, error)

Builds and signs a new JWT for a user with a specified time to live.

Returns `jsonBytes, nil` on success

The resultant JSON is a standard JWT string (`.` delimited, base64url encoded)

`ttl` is in seconds

func GetAllRecipeNames

func GetAllRecipeNames() ([]string, error)

Gathers all .cook recipes within the recipe root (possibly nested) and returns each as a relative filepath from recipe root.

Returns (nil, err) on failure

func GetAllRecipeNamesJSON

func GetAllRecipeNamesJSON() ([]byte, error)

Returns a JSON list of all recipe names (descended recursively) in the Recipes folder, as defined in the config.

Recipes are represented as a path relative to the recipes root.

func GetRecipeJSON

func GetRecipeJSON(name string) ([]byte, error)

Returns parsed and json econded recipe at provided relative filepath.

e.g. "breakfast/eggs_benedict"

	Considerations:
	- byte array will be nil on failure
 	- This can only read `.cook` files within the recipe directory.

func GetRecipeNamesPagedJSON

func GetRecipeNamesPagedJSON(n uint64, size uint64) ([]byte, error)

Builds a JSON list containing the `n`th page of recipes, using the provided page size.

Returns (jsonBytes, nil) on success, (nil, err) on failure

Out of bounds requests will return an empty array.

func GetRecipeSource

func GetRecipeSource(name string) ([]byte, error)

Returns raw byte data of recipe at provided relative filepath.

e.g. "breakfast/eggs_benedict"

	Considerations:
	- byte array will be nil on failure
 	- This can only read `.cook` files within the recipe directory.

func RenameRecipe

func RenameRecipe(name string, target string) error

Rename a recipe file using relative filepaths as input.

e.g. "breakfast/eggs_benedict" -> "lunch/deluxe_eggs_benedict"

Considerations:
- Returns nil on success, otherwise returns encountered error.
- Only affects ".cook" files within the recipe directory.
- Cleans up empty directories after a rename

func SearchRecipeNames

func SearchRecipeNames(query string) ([]string, error)

Returns a string list containing all recipes with names that match using the provided search pattern.

Search patterns are defined as:

• comma delimited terms
• each term is a tag (except for filters)
• directory filters can be written with a colon. e.g. `:breakfast/sweet`

each tag defined in the source under the metadata `tag` (comma delimited) are searched for.

func SearchRecipeNamesJSON

func SearchRecipeNamesJSON(query string) ([]byte, error)

Returns a JSON list containing all recipes with names that match using the provided search pattern.

See `SearchRecipeNames()` for details.

func SearchRecipeNamesPagedJSON

func SearchRecipeNamesPagedJSON(query string, n uint64, count uint64) ([]byte, error)

Returns a JSON list containing all recipes with names that match using the provided search pattern.

See `SearchRecipeNames` for details

func UpdateRecipe

func UpdateRecipe(name string, contents *[]byte) error

Replaces contents of specified recipe with `contents` Recipe is specified as a relative filepath from directory root

e.g. "breakfast/eggs_benedict"

Considerations:
- Returns nil on success, otherwise forwards errors.
- Can only affect ".cook" files
- Refuses to write empty files

func ValidateJWT

func ValidateJWT(token JWT) error

Validates a JWT with this server's key

Returns nil if the token is current and the signature is valid

Returns one of the following errors on failure which should likely be handled by case:

• ErrJWTFutureDated - `Issued` is in future
• ErrJWTExpired - `Expiry` has passed
• ErrJWTMismatch - `Signature` does not match generated one
• parsing/decoding errors

func ValidateJWTJSON

func ValidateJWTJSON(jsonBytes []byte) error

Validates a JWT with the servers key.

Returns nil on success

See `ValidateJWT` for more details

Types

type JWT

type JWT struct {
	Header  JWTHeader
	Payload JWTPayload

	Signature  string // Base64 URLEncoded checksum of all input data
	HeaderStr  string // Base64 URLEncoded JSON of Header
	PayloadStr string // Base64 URLEncoded JSON of Payload
}

An JSON web token for persistent authentication from a client

func DecodeJWTFromJSON

func DecodeJWTFromJSON(jsonBytes []byte) (JWT, error)

Decodes a JSON string into a JWT object

Returns token, nil on success

Invalid JSON or a malformed JWT string returns an error.

func GenerateJWT

func GenerateJWT(username string, issued int64, expiry int64) (JWT, error)

Builds and signs a new JWT for a user.

Returns `token, nil` on success

The token should not be used on error

type JWTHeader

type JWTHeader struct {
	Algorithm string `json:"alg"`
	Type      string `json:"typ"`
}

type JWTPayload

type JWTPayload struct {
	Username string `json:"sub"` // Username of user issued to
	Issued   int64  `json:"iat"` // Exact time of issue (seconds since epoch)
	Expires  int64  `json:"exp"` // Time of expiration (seconds since epoch)
}