api

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2024 License: GPL-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewMissionFromPlan 

func NewMissionFromPlan(plan *model.Plan) *mission.Mission

NewMissionFromPlan converts a plan into the equivalent mission for graph validation purposes. Not all fields will be included because the mission type will not use them func NewMissionFromPlan(plan *model.Plan) {

func SetLoggingFile 

func SetLoggingFile(logger *logrus.Logger, key string)

SetLoggingFile switches the logging output file to a file specific to the key and the current day. If no key is provided then logs go to the main logging file, which is only accessible by the admin.

Types

type API 

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

API is an instance of the Houston orchestration API

func New 

func New(configPath string) *API

New creates an instance of the Houston API object. It will create or connect to a database depending on the settings in the config file. local db will only persist while the program is running.

func (*API) ActiveMissions 

func (a *API) ActiveMissions(key string, plan string) []string

ActiveMissions finds all missions for a plan. If plan doesn't exist then an empty list is returned.

func (*API) AllActiveMissions 

func (a *API) AllActiveMissions(key string) ([]string, error)

AllActiveMissions finds all missions in the database for the key provided. Inactive/archived missions are not (or should not be) stored in the API database. Should only be used to check that there aren't any orphaned missions as this is less efficient than using ActiveMissions.

func (*API) CompletedMissions 

func (a *API) CompletedMissions(key string) []string

CompletedMissions returns a list all missionIds that are completed so that they can be archived and deleted.

func (*API) CreateKey 

func (a *API) CreateKey(key string, name string) (string, error)

CreateKey initialises a new key/project. This is a different concept to Redis keys. If the key already exists then it's name will be updated, but will otherwise be unchanged.

func (*API) CreateMissionFromPlan 

func (a *API) CreateMissionFromPlan(key string, planNameOrPlan string, missionId string, missionParameters map[string]interface{}) (string, error)

CreateMissionFromPlan creates new mission from an existing saved plan (given the name) or an unsaved plan (given entire plan as json). Does the following: - parse plan or get from db if name provided - validate DAG - assign mission ID if one is not provided - set start time - store in database - return created ID

func (*API) DeleteExpiredMissions 

func (a *API) DeleteExpiredMissions()

DeleteExpiredMissions looks for missions in the 'complete' and 'active' lists that are older than the Config.MissionExpiry time and deletes them

func (*API) DeleteKey 

func (a *API) DeleteKey(key string) error

func (*API) DeleteMission 

func (a *API) DeleteMission(key string, missionId string)

DeleteMission permanently deletes a mission from the database. If there are any errors these will be ignored to prevent the server from crashing.

func (*API) DeletePlan 

func (a *API) DeletePlan(w http.ResponseWriter, r *http.Request)

DeletePlan godoc @Summary Deletes a plan and all its missions from the database. @Description Deletes a plan and associated missions given its name. Any missions in progress will be deleted. @ID delete-plan @Tags Plan @Param x-access-key header string true "Houston Key" @Param Body body model.Plan true "The id, services, stages and parameters of a plan." @Param name path string true "The name of the plan" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/plans/{name} [delete]

func (*API) GetCompletedMissions 

func (a *API) GetCompletedMissions(w http.ResponseWriter, r *http.Request)

GetCompletedMissions godoc @Summary Returns the IDs of all completed missions. @Description Returns a list of the IDs of all completed (but not archived) missions for the key provided. These missions will also be in the list returned by GetMissions. This list is stored in a separate redis key for performance reasons. Completed missions should be deleted after being archived by the user to minimise the amount of storage required by the database. @ID get-completed @Tags Mission @Param x-access-key header string true "Houston Key" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/completed [post]

func (*API) GetKey 

func (a *API) GetKey(w http.ResponseWriter, r *http.Request)

GetKey godoc @Summary Get key information. @Description Returns key information (name and usage). @ID get-key @Tags Key @Param x-access-key header string true "Houston Key" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/key [get]

func (*API) GetKeyWebhook added in v0.6.0 

func (a *API) GetKeyWebhook(w http.ResponseWriter, r *http.Request)

GetKeyWebhook godoc @Summary Redirect to the dashboard UI and auto sign in with this key @Description Handles a GET request using the full base URL + key URL, i.e. "https://houston.example.com/api/v1/key/myhoustonkey". Redirects to the dashboard with the key as a parameter to automatically sign in with that key. @ID get-key-webhook @Tags Key @Param key path string true "Houston Key ID" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/key [get]

func (*API) GetLogs 

func (a *API) GetLogs(w http.ResponseWriter, r *http.Request)

GetLogs godoc @Summary Returns logs for the key provided. @Description Returns logs for the key provided. Defaults to today. @ID get-logs @Tags Logs @Param x-access-key header string true "Houston Key" @Param date query string false "Date of logs required in format YYYYMMDD" @Success 200 {string} string @Failure 404,500 {object} model.Error @Router /api/v1/logs [get]

func (*API) GetMission 

func (a *API) GetMission(w http.ResponseWriter, r *http.Request)

GetMission godoc @Summary Gets mission from ID. @Description Gets an existing mission using the ID provided. @ID get-mission @Tags Mission @Param x-access-key header string true "Houston Key" @Param id path string true "The id of the mission" @Success 200 {object} mission.Mission @Failure 404,500 {object} model.Error @Router /api/v1/missions/{id} [get]

func (*API) GetMissionReport 

func (a *API) GetMissionReport(w http.ResponseWriter, r *http.Request)

GetMissionReport godoc @Summary Gets a report of an existing mission. @Description Returns a report of an existing mission for a given Houston Key. @ID get-mission-report @Tags Mission @Param x-access-key header string true "Houston Key" @Param id path string true "The id of the mission" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/missions/{id}/report [get]

func (*API) GetMissions 

func (a *API) GetMissions(w http.ResponseWriter, r *http.Request)

GetMissions godoc @Summary Gets all existing missions. @Description Returns all existing missions for a given Houston Key. @ID get-missions @Tags Mission @Param x-access-key header string true "Houston Key" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/missions/ [get]

func (*API) GetPlan 

func (a *API) GetPlan(w http.ResponseWriter, r *http.Request)

GetPlan godoc @Summary Gets plan given its name. @Description Returns the plan definition as JSON. If the plan was never explicitly saved then it will return 404. @ID get-plan @Tags Plan @Param x-access-key header string true "Houston Key" @Param name path string true "The name of the plan" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/plans/{name} [get]

func (*API) GetPlanAsMission 

func (a *API) GetPlanAsMission(w http.ResponseWriter, r *http.Request)

GetPlanAsMission godoc @Summary Gets plan in format of a mission. @Description This is identical to GetPlan but returns the plan in the same format as a mission @ID get-plan-as-mission @Tags Plan @Param x-access-key header string true "Houston Key" @Param name path string true "The name of the plan" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/plans/{name}/m [get]

func (*API) GetPlanMissions 

func (a *API) GetPlanMissions(w http.ResponseWriter, r *http.Request)

GetPlanMissions godoc @Summary Gets a plan's missions @Description Returns a list of the IDs of all active (non archived) missions for the plan. @ID get-plan-missions @Tags Plan @Param x-access-key header string true "Houston Key" @Param name path string true "The name of the plan" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/plans/{name}/missions [get]

func (*API) GetPlans 

func (a *API) GetPlans(w http.ResponseWriter, r *http.Request)

GetPlans godoc @Summary Gets all plans @Description Returns a list of all existing plans given a Houston Key. @ID get-plans @Tags Plan @Param x-access-key header string true "Houston Key" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/plans/ [get]

func (*API) GetStatus 

func (a *API) GetStatus(w http.ResponseWriter, r *http.Request)

GetStatus godoc @Summary Get API status. @Description Check that the API is available and healthy. @ID status @Success 200 {object} model.Success @Failure 500 {object} model.Error @Router /api/v1 [get]

func (*API) HealthCheck 

func (a *API) HealthCheck()

func (*API) KeyIsValid added in v0.6.0 

func (a *API) KeyIsValid(key string) error

KeyIsValid checks that a key is valid and exists in the API database.

func (*API) ListKeys 

func (a *API) ListKeys(w http.ResponseWriter, r *http.Request)

ListKeys godoc @Summary Returns a list of all Houston keys. @Description @ID list-keys @Tags Key @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/key/all [get]

func (*API) ListPlans 

func (a *API) ListPlans(key string) ([]string, error)

ListPlans returns all plan names. The complete list of plans is the union of all saved plans and all active plans

func (*API) Monitor 

func (a *API) Monitor()

Monitor checks the health of the API server and performs other duties at regular intervals

func (*API) PostKey 

func (a *API) PostKey(w http.ResponseWriter, r *http.Request)

PostKey creates a new key. PostKey godoc @Summary Create a new key. @Description The request does not need to contain a body if a random key should be generated. The newly created key is returned as bytes. @ID post-key @Tags Key @Param Body body model.Key true "The id, name and usage of key" @Success 200 string key @Failure 404,500 {object} model.Error @Router /api/v1/key [post]

func (*API) PostMission 

func (a *API) PostMission(w http.ResponseWriter, r *http.Request)

PostMission godoc @Summary Creates a new mission and returns the ID. @Description Creates a new mission using the ID provided or with an automatically generated ID if none is provided. @ID create-mission @Tags Mission @Param x-access-key header string true "Houston Key" @Param Body body model.MissionCreateRequest true "The plan, ID, and parameters to give to the new mission." @Success 200 {object} model.MissionCreatedResponse @Failure 404,500 {object} model.Error @Router /api/v1/missions [post]

func (*API) PostMissionStage 

func (a *API) PostMissionStage(w http.ResponseWriter, r *http.Request)

PostMissionStage godoc @Summary Updates the state of a stage in an in-progress mission. @Description This route is transactional, meaning it will fail and result in 429 response if the same mission is currently being modified. @ID post-mission-stage @Tags Mission @Param x-access-key header string true "Houston Key" @Param Body body model.MissionStageStateUpdate true "The state of the stage and whether dependencies have been ignored." @Param id path string true "The id of the mission" @Param name path string true "The name of the plan" @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/missions/{id}/stages/{name} [post]

func (*API) PostPlan 

func (a *API) PostPlan(w http.ResponseWriter, r *http.Request)

PostPlan godoc @Summary Updates the state of a stage in an in-progress mission. @Description This route is transactional, meaning it will fail and result in 429 response if the same mission is currently being modified. @ID post-plan @Tags Plan @Param x-access-key header string true "Houston Key" @Param Body body model.Plan true "The id, services, stages and parameters of a plan." @Success 200 {object} model.Success @Failure 404,500 {object} model.Error @Router /api/v1/plans [post]

func (*API) Run 

func (a *API) Run()

Run starts the API server

func (*API) SavePlan 

func (a *API) SavePlan(key string, plan model.Plan) error

SavePlan stores a new plan in the database if that plan is valid. Current behaviour is to overwrite existing plans. The 'active' key for the plan, and any existing missions, will be unaffected if the plan already exists.

func (*API) SetPassword 

func (a *API) SetPassword(password string) error

func (*API) UpdateStageState 

func (a *API) UpdateStageState(key string, missionId string, stage string, state string, ignoreDependencies bool) (mission.Response, error)

UpdateStageState updates the state of a stage within an in-progress mission. POST /api/missions/[mission id]/stages/[stage name]

type Config 

type Config struct {
	Port           string          `yaml:"port" env:"HOUSTON_PORT" env-default:"8000" json:"port"`
	Redis          RedisConfig     `yaml:"redis" json:"redis"`
	Password       string          `yaml:"password" env:"HOUSTON_PASSWORD" json:"password"`
	Dashboard      DashboardConfig `yaml:"dashboard" json:"dashboard"`
	TLS            TLSConfig       `yaml:"tls" json:"tls"`
	MissionExpiry  time.Duration   `yaml:"mission_expiry" env:"HOUSTON_MISSION_EXPIRY" env-default:"720h"`     // 30 days
	MemoryLimitMiB int64           `yaml:"memory_limit_mib" env:"HOUSTON_MEMORY_LIMIT_MIB" env-default:"3072"` // 3GiB
	Salt           string          `json:"-"`                                                                  // note: it is not recommended to set the salt yourself. It will be randomly generated
}

func LoadConfig 

func LoadConfig(configPath string) Config

type DashboardConfig 

type DashboardConfig struct {
	Enabled bool   `yaml:"enabled" env:"HOUSTON_DASHBOARD" env-default:"true" json:"enabled"`
	Src     string `yaml:"src" env:"HOUSTON_DASHBOARD_SRC" env-default:"" json:"src"`
}

type IPRateLimiter 

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

func NewIPRateLimiter 

func NewIPRateLimiter(r rate.Limit, b int) *IPRateLimiter

func (*IPRateLimiter) AddIP 

func (i *IPRateLimiter) AddIP(ip string) *rate.Limiter

AddIP creates a new rate limiter and adds it to the ips map, using the IP address as the key

func (*IPRateLimiter) CleanUpIPs 

func (i *IPRateLimiter) CleanUpIPs()

CleanUpIPs will delete any rate limiters belonging to IPs that haven't been seen in over a minute

func (*IPRateLimiter) GetLimiter 

func (i *IPRateLimiter) GetLimiter(ip string) *rate.Limiter

GetLimiter returns the rate limiter for the provided IP address if it exists. Otherwise, calls AddIP to add IP address to the map

type RedisConfig 

type RedisConfig struct {
	Addr     string `yaml:"addr" env:"REDIS_ADDR" env-default:"localhost:6379" json:"addr"`
	Password string `yaml:"password" env:"REDIS_PASSWORD" env-default:"" json:"password"`
	DB       int    `yaml:"db" env:"REDIS_DB" env-default:"0" json:"db"`
}

type TLSConfig 

type TLSConfig struct {
	Auto     bool   `yaml:"auto" env:"TLS_AUTO" env-default:"true" json:"auto"`
	Host     string `yaml:"host" env:"TLS_HOST" env-default:"" json:"host"`
	CertFile string `yaml:"certFile" env:"TLS_CERT_FILE" env-default:"cert.pem" json:"certFile"`
	KeyFile  string `yaml:"keyFile" env:"TLS_KEY_FILE" env-default:"key.pem" json:"keyFile"`
}

type WebSocketClient 

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

WebSocketClient is a middleman between the websocket connection and the hub. We only want to send messages relating to a key if the client has that key.

type WebSocketHub 

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

WebSocketHub maintains the set of active clients and broadcasts messages to the clients. clients are grouped by key and are expected to provide the key when creating a connection.

Source Files

View all Source files

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.