From 425b80ab2a5e54d6e5b3f4c1f3f1314724eb4582 Mon Sep 17 00:00:00 2001 From: Chris Prather Date: Thu, 29 Oct 2020 04:00:07 -0400 Subject: [PATCH] bare bones documentation --- cli/config.go | 37 ++++++++--- cli/config_test.go | 4 +- cli/hardware.go | 6 +- cli/organizations.go | 2 +- conch/client.go | 82 ++++++++++++++++++++++-- conch/conch.go | 24 +++++-- conch/datacenters.go | 18 ++++-- conch/deviceReports.go | 10 ++- conch/devices.go | 98 ++++++++++++++++++---------- conch/hardwareProducts.go | 22 +++++-- conch/hardwareVendors.go | 39 ++++++++---- conch/hardwareVendors_test.go | 4 +- conch/organizations.go | 30 +++++---- conch/organizations_test.go | 2 +- conch/rackRoles.go | 16 +++-- conch/racks.go | 51 ++++++++++----- conch/relays.go | 16 +++-- conch/rooms.go | 64 +++++++++++++------ conch/schema.go | 6 +- conch/users.go | 117 +++++++++++++++++++++------------- conch/users_test.go | 23 +++++-- conch/validations.go | 32 +++++++--- logger/logger.go | 13 ++++ tables/tables.go | 9 +++ template/template.go | 10 ++- 25 files changed, 529 insertions(+), 206 deletions(-) diff --git a/cli/config.go b/cli/config.go index 130c819..c2c837e 100644 --- a/cli/config.go +++ b/cli/config.go @@ -14,6 +14,7 @@ import ( "github.com/joyent/kosh/template" ) +// Config is the interface for the configuration object for the full app type Config interface { GetVersion() string @@ -32,7 +33,7 @@ type Config interface { conch.Config } -// Config struct +// DefaultConfig is the default configuration struct type DefaultConfig struct { Version string GitRev string @@ -46,15 +47,31 @@ type DefaultConfig struct { logger.Logger } -func (c *DefaultConfig) GetVersion() string { return c.Version } -func (c *DefaultConfig) GetURL() string { return c.ConchURL } -func (c *DefaultConfig) GetToken() string { return c.ConchToken } +// GetVersion returns the current app version +func (c *DefaultConfig) GetVersion() string { return c.Version } + +// GetURL returns the current conch API url +func (c *DefaultConfig) GetURL() string { return c.ConchURL } + +// GetToken returns the current conch API token +func (c *DefaultConfig) GetToken() string { return c.ConchToken } + +// GetLogger returns the current logger instance func (c *DefaultConfig) GetLogger() logger.Logger { return c.Logger } -func (c *DefaultConfig) SetURL(URL string) { c.ConchURL = URL } -func (c *DefaultConfig) SetToken(token string) { c.ConchToken = token } -func (c *DefaultConfig) GetOutputJSON() bool { return c.OutputJSON } -func (c *DefaultConfig) SetOutputJSON(p bool) { c.OutputJSON = p } +// SetURL updates the current conch API url +func (c *DefaultConfig) SetURL(URL string) { c.ConchURL = URL } + +// SetToken updates the current conch API token being used +func (c *DefaultConfig) SetToken(token string) { c.ConchToken = token } + +// GetOutputJSON returns whether JSON is used for output or not +func (c *DefaultConfig) GetOutputJSON() bool { return c.OutputJSON } + +// SetOutputJSON sets whether to use JSOn for output or not +func (c *DefaultConfig) SetOutputJSON(p bool) { c.OutputJSON = p } + +// SetLogger sets the configured logger instance func (c *DefaultConfig) SetLogger(l logger.Logger) { c.Logger = l } // NewConfig takes a Version and a GitRev and returns a Config object @@ -81,6 +98,7 @@ const configTemplate = ` --- ` +// String returns a string implementation of the config object func (c *DefaultConfig) String() string { t, err := template.NewTemplate().Parse(configTemplate) if err != nil { @@ -100,6 +118,7 @@ func (c *DefaultConfig) ConchClient() *conch.Client { return conch.New(c).UserAgent(userAgent) } +// Renderer returns a function that will render to STDOUT func (c *DefaultConfig) Renderer() func(interface{}) { return c.RenderTo(os.Stdout) } @@ -112,6 +131,8 @@ func renderJSON(i interface{}) string { return string(b) } +// RenderTo returns a function tha renders to a given io.Writer based on the +// configuraton and datatype func (c *DefaultConfig) RenderTo(w io.Writer) func(interface{}) { return func(i interface{}) { if c.OutputJSON { diff --git a/cli/config_test.go b/cli/config_test.go index 970e8cf..d5ef862 100644 --- a/cli/config_test.go +++ b/cli/config_test.go @@ -198,7 +198,7 @@ func TestRender(t *testing.T) { { Name: " display(conch.GetHardwareVendors())", - Do: func() { display(conch.GetHardwareVendors()) }, + Do: func() { display(conch.GetAllHardwareVendors()) }, }, { @@ -208,7 +208,7 @@ func TestRender(t *testing.T) { { Name: " display(conch.GetOrganizations())", - Do: func() { display(conch.GetOrganizations()) }, + Do: func() { display(conch.GetAllOrganizations()) }, }, { diff --git a/cli/hardware.go b/cli/hardware.go index 1297e3f..5f33f7d 100644 --- a/cli/hardware.go +++ b/cli/hardware.go @@ -26,7 +26,7 @@ func cmdCreateProduct(cfg Config) func(*cli.Cmd) { cmd.Action = func() { conch := cfg.ConchClient() validationPlan := conch.GetValidationPlanByName(*validationPlanOpt) - vendor := conch.GetHardwareVendorByID(*vendor) + vendor := conch.GetHardwareVendorByName(*vendor) create := types.HardwareProductCreate{ Name: types.MojoStandardPlaceholder(*name), Alias: types.MojoStandardPlaceholder(*alias), @@ -91,7 +91,7 @@ func hardwareCmd(cfg Config) func(*cli.Cmd) { cmd.Command("vendors", "Work with hardware vendors", func(cmd *cli.Cmd) { cmd.Command("get ls", "Get a list of all hardware vendors", func(cmd *cli.Cmd) { - display(conch.GetHardwareVendors()) + display(conch.GetAllHardwareVendors()) }) cmd.Command("create", "Create a hardware vendor", func(cmd *cli.Cmd) { name := cmd.StringArg("NAME", "", "The name of the hardware vendor.") @@ -107,7 +107,7 @@ func hardwareCmd(cfg Config) func(*cli.Cmd) { // grab the Vendor for the given ID cmd.Before = func() { - hv = conch.GetHardwareVendorByID(*idArg) + hv = conch.GetHardwareVendorByName(*idArg) if (hv == types.HardwareVendor{}) { fmt.Println("Hardware Vendor not found for " + *idArg) cli.Exit(1) diff --git a/cli/organizations.go b/cli/organizations.go index fe9a842..a573200 100644 --- a/cli/organizations.go +++ b/cli/organizations.go @@ -16,7 +16,7 @@ func organizationsCmd(cfg Config) func(cmd *cli.Cmd) { } cmd.Command("get ls", "Get a list of all organizations", func(cmd *cli.Cmd) { cmd.Action = func() { - display(conch.GetOrganizations()) + display(conch.GetAllOrganizations()) } }) diff --git a/conch/client.go b/conch/client.go index 627be61..8d139a9 100644 --- a/conch/client.go +++ b/conch/client.go @@ -14,11 +14,14 @@ import ( "github.com/joyent/kosh/logger" ) +// Client is a struct that represnts the current Conch client. type Client struct { Sling *sling.Sling logger.Logger } +// Config is an interface for an acceptable struct to configure the conch +// client. type Config interface { GetURL() string GetToken() string @@ -40,6 +43,7 @@ func defaultUserAgent() string { return fmt.Sprintf("go-conch %s", filepath.Base(f)) } +// New takes a Config struct and returns a new instance of Client func New(c Config) *Client { c.GetLogger().Debug(c) s := sling.New(). @@ -51,18 +55,23 @@ func New(c Config) *Client { return &Client{s, c.GetLogger()} } +// New performs a shallow clone of the current client and returns the +// new instance func (c *Client) New() *Client { s := c.Sling.New() l := c.Logger return &Client{s, l} } +// UserAgent sets the client's User-Agent header to the given string func (c *Client) UserAgent(ua string) *Client { c = c.New() c.Sling.Set("User-Agent", ua) return c } +// Path sets the sling path to the given path, optionally appending 0 or +// more IDs to the end of the path func (c *Client) Path(path string, ids ...string) *Client { c = c.New() c.Sling.Path(fmt.Sprintf("%s/", path)) @@ -74,96 +83,140 @@ func (c *Client) Path(path string, ids ...string) *Client { return c } +// Token sets the last element in the pasth to token and optionally to the given +// token identifier func (c *Client) Token(id ...string) *Client { return c.Path("token", id...) } +// Relay sets the last element in the path to /relay and optionally appends the +// given relay identifier func (c *Client) Relay(id ...string) *Client { return c.Path("relay", id...) } +// Register sets the last element in the path to /register func (c *Client) Register() *Client { return c.Path("register") } +// HardwareVendor sets the last element in the path to /hardware_vendor and +// optionally appends teh given Hardare Vendor identifiers func (c *Client) HardwareVendor(id ...string) *Client { return c.Path("hardware_vendor", id...) } +// HardwareProduct sets the last element in the path to /hardware_product and +// optionally appends the given Hardare Product identifiers func (c *Client) HardwareProduct(id ...string) *Client { return c.Path("hardware_product", id...) } +// Specification sets the last element in the path to /specification and +// optionally sets the path query string func (c *Client) Specification(path ...string) *Client { return c.Path("specification"). stripTrailingSlash(). Path(fmt.Sprintf("?path=%s", path)) } +// DC sets the last element in the path to /dc and +// appends the given identifiers func (c *Client) DC(id ...string) *Client { return c.Path("dc", id...) } +// Rooms sets the last element in the path to /rooms and +// appends the given identifiers func (c *Client) Rooms() *Client { return c.Path("rooms") } +// User sets the last element in the path to /user and +// appends the given identifiers func (c *Client) User(id ...string) *Client { return c.Path("user", id...) } +// Device sets the last element in the path to /device and +// appends the given identifiers func (c *Client) Device(id ...string) *Client { return c.Path("device", id...) } +// Settings sets the last element in the path to /settings and +// appends the given identifiers func (c *Client) Settings(id ...string) *Client { return c.Path("settings", id...) } +// Build sets the last element in the path to /build and +// appends the given identifiers func (c *Client) Build(id ...string) *Client { return c.Path("build", id...) } +// Organization sets the last element in the path to /organization and +// appends the given identifiers func (c *Client) Organization(id ...string) *Client { return c.Path("organization", id...) } +// Rack sets the last element in the path to /rack and +// appends the given identifiers func (c *Client) Rack(id ...string) *Client { return c.Path("rack", id...) } +// RackRole sets the last element in the path to /rack_role and +// appends the given identifiers func (c *Client) RackRole(id ...string) *Client { return c.Path("rack_role", id...) } +// Room sets the last element in the path to /room and +// appends the given identifiers func (c *Client) Room(id ...string) *Client { return c.Path("room", id...) } +// Layout sets the last element in the path to /layout and +// appends the given identifiers func (c *Client) Layout(id ...string) *Client { return c.Path("layout", id...) } +// Validation sets the last element in the path to /validation and +// appends the given identifiers func (c *Client) Validation(id ...string) *Client { return c.Path("validation", id...) } +// ValidationPlan sets the last element in the path to /validation_plan and +// appends the given identifiers func (c *Client) ValidationPlan(id ...string) *Client { return c.Path("validation_plan", id...) } +// ValidationState sets the last element in the path to /validation_state and +// appends the given identifiers func (c *Client) ValidationState(id ...string) *Client { return c.Path("validation_state", id...) } +// Interface sets the last element in the path to /interface and +// appends the given identifiers func (c *Client) Interface(id ...string) *Client { return c.Path("interface", id...) } +// Schema sets the last element in the path to /schema and +// appends the given identifiers func (c *Client) Schema(name ...string) *Client { return c.Path("schema", name...) } +// Field appends the given identifiers func (c *Client) Field(ids ...string) *Client { c = c.New() for _, id := range ids { @@ -180,10 +233,11 @@ func (c *Client) stripTrailingSlash() *Client { return c } -func (c *Client) WithParams(settings map[string]string) *Client { +// WithParams sets the query arguments to the given key values in the params map +func (c *Client) WithParams(params map[string]string) *Client { c = c.stripTrailingSlash() segments := []string{} - for k, v := range settings { + for k, v := range params { segments = append(segments, fmt.Sprintf("%s=%s&", url.PathEscape(k), url.PathEscape(v))) } qs := strings.Join(segments, "&") @@ -191,68 +245,85 @@ func (c *Client) WithParams(settings map[string]string) *Client { return c } +// ValidationStates sets the last element in the path to /validation_state +// BUG(perigrin) Doesn't support query parameters yet func (c *Client) ValidationStates(states ...string) *Client { c = c.New() c.Sling.Path("validation_state") // TODO add query params from states return c } +// SKU sets the last element in the path to /sku func (c *Client) SKU() *Client { return c.Path("sku") } +// Assignment sets the last element in the path to /assignment func (c *Client) Assignment() *Client { return c.Path("assignment") } +// Links sets the last element in the path to /links func (c *Client) Links() *Client { return c.Path("links") } +// PXE sets the last element in the path to /pxe func (c *Client) PXE() *Client { return c.Path("pxe") } +// Location sets the last element in the path to /location func (c *Client) Location() *Client { return c.Path("location") } +// Revoke sets the last element in the path to /revoke func (c *Client) Revoke() *Client { return c.Path("revoke") } +// Password sets the last element in the path to /password func (c *Client) Password() *Client { return c.Path("password") } +// AssetTag sets the last element in the path to /asset_tag func (c *Client) AssetTag() *Client { return c.Path("asset_tag") } +// Validated sets the last element in the path to /validated func (c *Client) Validated() *Client { return c.Path("validated") } +// Phase sets the last element in the path to /phase func (c *Client) Phase() *Client { return c.Path("phase") } +// DeviceReport sets the last element in the path to /device_report and appends +// the given identifier func (c *Client) DeviceReport(id ...string) *Client { return c.Path("device_report", id...) } +// Post sets the HTTP method to POST and sets the JSON body to the given data func (c *Client) Post(data interface{}) *Client { c = c.New() c.Sling.Post("").BodyJSON(data) return c } +// Put sets the HTTP method to PUT and sets the JSON body to the given data func (c *Client) Put(data interface{}) *Client { c = c.New() c.Sling.Put("").BodyJSON(data) return c } +// Delete sets the HTTP method to DELETE and optionally sets the JSON body to the given data func (c *Client) Delete(data ...interface{}) *Client { c = c.New() c.Sling.Delete("") @@ -262,7 +333,8 @@ func (c *Client) Delete(data ...interface{}) *Client { return c } -// when you don't expect a response +// Send sends a HTTP request to the API server without expecting a return data +// structure. It returns the *http.Response and/or error from the request. func (c *Client) Send() (*http.Response, error) { c.Debug("Send") req, err := c.Sling.Request() @@ -275,7 +347,9 @@ func (c *Client) Send() (*http.Response, error) { return res, err } -// when you do expect a response +// Receive sends a HTTP request to the API server and decodes the results into +// the provided structure structure. It returns the *http.Response and/or error +// from the request. func (c *Client) Receive(data interface{}) (*http.Response, error) { c.Debug("Receive") req, err := c.Sling.Request() diff --git a/conch/conch.go b/conch/conch.go index dfa2440..6a763bc 100644 --- a/conch/conch.go +++ b/conch/conch.go @@ -1,37 +1,51 @@ +/* +Package conch provivides a wrapper around the Conch-API web service. For more +inforamtion about the Conch-API, including documentation for the endpoints that +this library wraps, please see: https://joyent.github.io/conch-api/ +*/ package conch import "github.com/joyent/kosh/conch/types" -// GET /ping +// Ping ( GET /ping ) checks to see if the API server is online and reachable. +// See also https://joyent.github.io/conch-api/modules/Conch::Route#get-ping func (c *Client) Ping() (ping types.Ping) { c.Path("ping").Receive(&ping) return } -// GET /version +// Version ( GET /version ) returns the conch-api version See also +// https://joyent.github.io/conch-api/modules/Conch::Route#get-version func (c *Client) Version() (version types.Version) { c.Path("version").Receive(&version) return } -// POST /login +// Login ( POST /login ) takes a username and password and returns a session +// token from the server. See also also +// https://joyent.github.io/conch-api/modules/Conch::Route#post-login func (c *Client) Login(user, pass string) (token types.LoginToken) { c.Path("login").Post(types.Login{Email: types.EmailAddress(user), Password: types.NonEmptyString(pass)}).Receive(&token) return } -// POST /logout +// Logout ( POST /logout ) terminates a login token on the server. See also +// https://joyent.github.io/conch-api/modules/Conch::Route#post-logout func (c *Client) Logout() error { _, e := c.Path("logout").Post("").Send() return e } -// POST /refresh_token +// RefreshToken ( POST /refresh_token ) uses the current login token to +// generate a *new* login token. See also +// https://joyent.github.io/conch-api/modules/Conch::Route#post-refresh_token func (c *Client) RefreshToken() (token types.LoginToken) { c.Path("refresh_token").Post("").Receive(&token) return } +// IsSysAdmin is a helper function that uses GetCurrentUser to figure out if +// the current user is a system admin or not. func (c *Client) IsSysAdmin() bool { return c.GetCurrentUser().IsAdmin } diff --git a/conch/datacenters.go b/conch/datacenters.go index 739cf75..fd32057 100644 --- a/conch/datacenters.go +++ b/conch/datacenters.go @@ -2,42 +2,48 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /dc +// GetAllDatacenters ( GET /dc ) retrieves a list of all datacenters func (c *Client) GetAllDatacenters() (dc types.Datacenters) { c.DC("").Receive(&dc) return } -// POST /dc +// CreateDatacenter (POST /dc) posts a new Datacenter to teh API func (c *Client) CreateDatacenter(dc types.DatacenterCreate) error { _, e := c.DC("").Post(dc).Send() return e } -// GET /dc/:datacenter_id +// GetDatacenterByName ( GET /dc/:datacenter_id ) fetches a new datacenter +// using the given string func (c *Client) GetDatacenterByName(name string) (dc types.Datacenter) { c.DC(name).Receive(&dc) return } +// GetDatacenterByID ( GET /dc/:datacenter_id ) fetches a new datacenter using +// the given UUID func (c *Client) GetDatacenterByID(id types.UUID) (dc types.Datacenter) { c.DC(id.String()).Receive(&dc) return } -// POST /dc/:datacenter_id +// UpdateDatacenter (POST /dc/:datacenter_id) updates datacenter with the given +// UUID func (c *Client) UpdateDatacenter(id types.UUID, update types.DatacenterUpdate) error { _, e := c.DC(id.String()).Post(update).Send() return e } -// DELETE /dc/:datacenter_id +// DeleteDatacenter (DELETE /dc/:datacenter_id) removes the given datacenter +// from the API func (c *Client) DeleteDatacenter(id types.UUID) error { _, e := c.DC(id.String()).Delete().Send() return e } -// GET /dc/:datacenter_id/rooms +// GetAllDatacenterRooms ( GET /dc/:datacenter_id/rooms ) retrieves a list fo +// rooms in the given datacenter func (c *Client) GetAllDatacenterRooms(id types.UUID) (rooms types.DatacenterRoomsDetailed) { c.DC(id.String()).Rooms().Receive(&rooms) return diff --git a/conch/deviceReports.go b/conch/deviceReports.go index 2b2580d..d2a1bd9 100644 --- a/conch/deviceReports.go +++ b/conch/deviceReports.go @@ -7,7 +7,8 @@ import ( "github.com/joyent/kosh/conch/types" ) -// POST /device_report +// SendDeviceReport (POST /device_report) reads a new device report from an +// io.Reader and sends it to the API, it does not return the results func (c *Client) SendDeviceReport(r io.Reader) error { report := &types.DeviceReport{} json.NewDecoder(r).Decode(report) @@ -15,7 +16,9 @@ func (c *Client) SendDeviceReport(r io.Reader) error { return e } -// POST /device_report?no_update_db=1 +// ValidateDeviceReport (POST /device_report?no_update_db=1) reads a new device +// report from an io.Reader and sends it to the API returning the validation +// results func (c *Client) ValidateDeviceReport(r io.Reader) (results types.ReportValidationResults) { report := &types.DeviceReport{} json.NewDecoder(r).Decode(report) @@ -23,7 +26,8 @@ func (c *Client) ValidateDeviceReport(r io.Reader) (results types.ReportValidati return } -// GET /device_report/:device_report_id +// GetDeviceReport (GET /device_report/:device_report_id) returns the +// previously sent report for the given id string func (c *Client) GetDeviceReport(id string) (report types.DeviceReportRow) { c.DeviceReport(id).Receive(&report) return diff --git a/conch/devices.go b/conch/devices.go index 68ad040..2327202 100644 --- a/conch/devices.go +++ b/conch/devices.go @@ -1,8 +1,3 @@ -/* - -API Wrapper for https://joyent.github.io/conch-api/modules/Conch::Route::Device - -*/ package conch import ( @@ -11,192 +6,231 @@ import ( "github.com/joyent/kosh/conch/types" ) -// GET /device?:key=:value +// FindDevicesBySetting (GET /device?:key=:value) returns a list of devices +// that have the matching setting func (c *Client) FindDevicesBySetting(key, value string) (device types.Devices) { c.Device("").WithParams(map[string]string{key: value}).Receive(&device) return } +// FindDevicesByTag (GET /device?:key=:value) returns a list of devices that +// have the matching tag func (c *Client) FindDevicesByTag(key, value string) (device types.Devices) { key = fmt.Sprintf("tag_%s", key) c.Device("").WithParams(map[string]string{key: value}).Receive(&device) return } +// FindDevicesByField (GET /device?:key=:value) returns a list of devices that +// have the matching field func (c *Client) FindDevicesByField(key, value string) (device types.Device) { c.Device("").WithParams(map[string]string{key: value}).Receive(&device) return } -// GET /device/:device_id_or_serial_number +// GetDeviceBySerial (GET /device/:device_id_or_serial_number) retrieves a +// specific device by the given serial number string func (c *Client) GetDeviceBySerial(serial string) (device types.DetailedDevice) { c.Device(serial).Receive(&device) return } -// GET /device/:device_id_or_serial_number +// GetDeviceByID (GET /device/:device_id_or_serial_number) retrieves a specific +// device by the given UUID func (c *Client) GetDeviceByID(id types.UUID) (device types.DetailedDevice) { c.Device(id.String()).Receive(&device) return } -// GET /device/:device_id_or_serial_number/pxe +// GetDevicePXE (GET /device/:device_id_or_serial_number/pxe) returns the PXE +// information for the given device func (c *Client) GetDevicePXE(id string) (pxe types.DevicePXE) { c.Device(id).PXE().Receive(&pxe) return } -// GET /device/:device_id_or_serial_number/phase +// GetDevicePhase (GET /device/:device_id_or_serial_number/phase) returns teh +// Phase for the given device func (c *Client) GetDevicePhase(id string) (phase types.DevicePhase) { c.Device(id).Phase().Receive(&phase) return } -// GET /device/:device_id_or_serial_number/sku +// GetDeviceSKU (GET /device/:device_id_or_serial_number/sku) returns the SKU +// for the given device func (c *Client) GetDeviceSKU(id string) (sku types.DeviceSku) { c.Device(id).SKU().Receive(&sku) return } -// POST /device/:device_id_or_serial_number/asset_tag +// SetDeviceAssetTag (POST /device/:device_id_or_serial_number/asset_tag) sets +// a new asset tag for the given device func (c *Client) SetDeviceAssetTag(id string, tag types.DeviceAssetTag) error { _, e := c.Device(id).AssetTag().Post(tag).Send() return e } -// POST /device/:device_id_or_serial_number/asset_tag +// SetDeviceValidated (POST /device/:device_id_or_serial_number/validated) sets +// the validated field on the given device. THIS IS DEPRECATED. func (c *Client) SetDeviceValidated(id string) error { _, e := c.Device(id).Validated().Post("").Send() return e } -// POST /device/:device_id_or_serial_number/phase +// SetDevicePhase (POST /device/:device_id_or_serial_number/phase) this sets +// the phase on the given device func (c *Client) SetDevicePhase(id, phase string) error { _, e := c.Device(id).Phase().Post(types.DevicePhase(phase)).Send() return e } -// POST /device/:device_id_or_serial_number/links +// SetDeviceLinks (POST /device/:device_id_or_serial_number/links) sets the +// links on the given device func (c *Client) SetDeviceLinks(id string, links types.DeviceLinks) error { _, e := c.Device(id).Links().Post(links).Send() return e } -// DELETE /device/:device_id_or_serial_number/links +// DeleteDeviceLinks (DELETE /device/:device_id_or_serial_number/links) removes +// the links for the given device func (c *Client) DeleteDeviceLinks(id string) error { _, e := c.Device(id).Links().Delete().Send() return e } -// POST /device/:device_id_or_serial_number/hardware_product -// POST /device/:device_id_or_serial_number/sku +// SetDeviceSKU (POST /device/:device_id_or_serial_number/sku) updates teh SKU +// for the given device func (c *Client) SetDeviceSKU(id string, hardware types.DeviceHardware) error { _, e := c.Device(id).SKU().Post(hardware).Send() return e } -// POST /device/:device_id_or_serial_number/links +// SetDeviceBuild (POST /device/:device_id_or_serial_number/build) updates teh +// build for the given device func (c *Client) SetDeviceBuild(id string, build types.DeviceBuild) error { _, e := c.Device(id).Build("").Post(build).Send() return e } -// GET /device/:device_id_or_serial_number/location +// GetDeviceLocation (GET /device/:device_id_or_serial_number/location) returns +// the known location data for the given device, this data is only accurate +// whhile the device is in preflight func (c *Client) GetDeviceLocation(id string) (location types.DeviceLocation) { c.Device(id).Location().Receive(&location) return } -// POST /device/:device_id_or_serial_number/location +// SetDeviceLocation (POST /device/:device_id_or_serial_number/location) +// udpates the current device location information for the given device func (c *Client) SetDeviceLocation(id string, location types.DeviceLocationUpdate) error { _, e := c.Device(id).Location().Post(location).Send() return e } -// DELETE /device/:device_id_or_serial_number/location +// DeleteDeviceLocation (DELETE /device/:device_id_or_serial_number/location) +// removes the given device location information for the given device func (c *Client) DeleteDeviceLocation(id string) error { _, e := c.Device(id).Location().Delete().Send() return e } -// GET /device/:device_id_or_serial_number/settings +// GetDeviceSettings (GET /device/:device_id_or_serial_number/settings) +// retrieves the current settings for teh given device func (c *Client) GetDeviceSettings(id string) (settings types.DeviceSettings) { c.Device(id).Settings("").Receive(&settings) return } -// POST /device/:device_id_or_serial_number/settings +// SetDeviceSettings (POST /device/:device_id_or_serial_number/settings) +// updates the current settings for the given device func (c *Client) SetDeviceSettings(id string, settings types.DeviceSettings) error { _, e := c.Device(id).Settings("").Post(settings).Send() return e } -// GET /device/:device_id_or_serial_number/settings/:key +// GetDeviceSettingByName (GET /device/:device_id_or_serial_number/settings/:key) +// retrieves a single device setting by name func (c *Client) GetDeviceSettingByName(id, name string) (setting types.DeviceSetting) { c.Device(id).Settings(name).Receive(&setting) return } +// GetDeviceTags (GET /device/:device_id_or_serial_number/settings/:key) +// retrieves the tags for a given device func (c *Client) GetDeviceTags(id string) (tags types.DeviceSettings) { c.Device(id).Settings("").Receive(&tags) return } +// GetDeviceTagByName (GET /device/:device_id_or_serial_number/settings/:key) +// retrieves a current tag by name for a given device func (c *Client) GetDeviceTagByName(id, name string) (tag types.DeviceSetting) { name = fmt.Sprintf("tag_%s", name) c.Device(id).Settings(name).Receive(&tag) return } +// SetDeviceTag (POST /device/:device_id_or_serial_number/settings/:key) +// updates a current tag by name for the given device func (c *Client) SetDeviceTag(id, name, value string) error { name = fmt.Sprintf("tag_%s", name) _, e := c.Device(id).Settings(name).Post(value).Send() return e } +// DeleteDeviceTag (POST /device/:device_id_or_serial_number/settings/:key) +// removes a current tag by name for the given device func (c *Client) DeleteDeviceTag(id, name string) error { name = fmt.Sprintf("tag_%s", name) _, e := c.Device(id).Settings(name).Delete().Send() return e } -// POST /device/:device_id_or_serial_number/settings/:key +// SetDeviceSetting (POST /device/:device_id_or_serial_number/settings/:key) +// updates a device setting by name for the given device func (c *Client) SetDeviceSetting(id, name, value string) error { _, e := c.Device(id).Settings(name).Post(value).Send() return e } -// DELETE /device/:device_id_or_serial_number/settings/:key +// DeleteDeviceSetting (DELETE /device/:device_id_or_serial_number/settings/:key) +// removes a device setting by name for the given device func (c *Client) DeleteDeviceSetting(id, name string) error { _, e := c.Device(id).Settings(name).Delete().Send() return e } -// POST /device/:device_id_or_serial_number/validation/:validation_id +// RunValidationForDevice (POST /device/:device_id_or_serial_number/validation/:validation_id) +// runs a named validation for the given device and returns (but does not save) +// the results func (c *Client) RunValidationForDevice(device, validation string, report types.DeviceReport) (results types.ValidationResults) { c.Device(device).Validation(validation).Post(report).Receive(&results) return } -// GET /device/:device_id_or_serial_number/validation_state?status=&status=... +// GetDeviceValidationStates ( GET /device/:device_id_or_serial_number/validation_state?status=&status=...) +// retrieves the given validation results for teh given device func (c *Client) GetDeviceValidationStates(id string, states ...string) (validations types.ValidationStateWithResults) { c.Device(id).ValidationStates(states...).Receive(&validations) return } -// GET /device/:device_id_or_serial_number/interface +// GetDeviceInterfaces (GET /device/:device_id_or_serial_number/interface) +// returns the reported interface information for the given device func (c *Client) GetDeviceInterfaces(id string) (nics types.DeviceNics) { c.Device(id).Interface("").Receive(&nics) return } -// GET /device/:device_id_or_serial_number/interface +// GetDeviceInterfaceByName (GET /device/:device_id_or_serial_number/interface) +// returns the information for a specific interface for the given device func (c *Client) GetDeviceInterfaceByName(id, name string) (nic types.DeviceNic) { c.Device(id).Interface(name).Receive(&nic) return } -// GET /device/:device_id_or_serial_number/interface +// GetDeviceInterfaceField (GET /device/:device_id_or_serial_number/interface) +// retrieves a specific property of the named interface for a given device func (c *Client) GetDeviceInterfaceField(id, name, field string) (nicField types.DeviceNicField) { c.Device(id).Interface(name).Field(field).Receive(&nicField) return diff --git a/conch/hardwareProducts.go b/conch/hardwareProducts.go index 73201c1..3b06bf8 100644 --- a/conch/hardwareProducts.go +++ b/conch/hardwareProducts.go @@ -2,43 +2,51 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /hardware_product +// GetHardwareProducts (GET /hardware_product) returns a list of known hardware +// products func (c *Client) GetHardwareProducts() (products types.HardwareProducts) { c.HardwareProduct().Receive(&products) return } -// POST /hardware_product +// CreateHardwareProduct (POST /hardware_product) creates a new hardware +// product func (c *Client) CreateHardwareProduct(product types.HardwareProductCreate) error { _, e := c.HardwareProduct().Post(product).Send() return e } -// GET /hardware_product/:hardware_product_id_or_other +// GetHardwareProductByID (GET /hardware_product/:hardware_product_id_or_other) +// returns a hardware product by the given id string func (c *Client) GetHardwareProductByID(id string) (products types.HardwareProduct) { c.HardwareProduct(id).Receive(&products) return } -// POST /hardware_product/:hardware_product_id_or_other +// UpdateHardwareProduct (POST /hardware_product/:hardware_product_id_or_other) +// updates the given hardware product information func (c *Client) UpdateHardwareProduct(id string, update types.HardwareProductUpdate) error { _, e := c.HardwareProduct(id).Post(update).Send() return e } -// DELETE /hardware_product/:hardware_product_id_or_other +// DeleteHardwareProduct (DELETE /hardware_product/:hardware_product_id_or_other) +// removes a hardware product func (c *Client) DeleteHardwareProduct(id types.UUID) error { _, e := c.HardwareProduct(id.String()).Delete().Send() return e } -// PUT /hardware_product/:hardware_product_id_or_other/specification?path=:path_to_data +// UpdateHardwareProductSpecification (PUT /hardware_product/:hardware_product_id_or_other/specification?path=:path_to_data) +// updates the Hardware Product Specification information at the given path for +// the given hardware product func (c *Client) UpdateHardwareProductSpecification(id, path string, update types.HardwareProductSpecification) error { _, e := c.HardwareProduct(id).Specification(path).Put(update).Send() return e } -// DELETE /hardware_product/:hardware_product_id_or_other/specification?path=:path_to_data +// DeleteHardwareProductSpecification (DELETE /hardware_product/:hardware_product_id_or_other/specification?path=:path_to_data) +// removes the specification at teh given path for the given hardware product func (c *Client) DeleteHardwareProductSpecification(id, path string) error { _, e := c.HardwareProduct(id).Specification(path).Delete().Send() return e diff --git a/conch/hardwareVendors.go b/conch/hardwareVendors.go index 0301e73..5c7e23f 100644 --- a/conch/hardwareVendors.go +++ b/conch/hardwareVendors.go @@ -2,35 +2,48 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /hardware_vendor -func (c *Client) GetHardwareVendors() (vendors types.HardwareVendors) { +// GetAllHardwareVendors (GET /hardware_vendor) returns a list of all hardware +// vendors +func (c *Client) GetAllHardwareVendors() (vendors types.HardwareVendors) { c.HardwareVendor().Receive(&vendors) return } -// GET /hardware_vendor/:hardware_vendor_id_or_name -func (c *Client) GetHardwareVendorByID(id string) (vendor types.HardwareVendor) { - c.HardwareVendor(id).Receive(&vendor) +// GetHardwareVendorByName (GET /hardware_vendor/:hardware_vendor_id_or_name) +// returns a specific hardware vendor by the given name +func (c *Client) GetHardwareVendorByName(name string) (vendor types.HardwareVendor) { + c.HardwareVendor(name).Receive(&vendor) return } -// DELETE /hardware_vendor/:hardware_vendor_id_or_name +// GetHardwareVendorByID (GET /hardware_vendor/:hardware_vendor_id_or_name) +// returns a specific hardware vendor by the given UUID +func (c *Client) GetHardwareVendorByID(id types.UUID) (vendor types.HardwareVendor) { + c.HardwareVendor(id.String()).Receive(&vendor) + return +} + +// DeleteHardwareVendor (DELETE /hardware_vendor/:hardware_vendor_id_or_name) +// removes the hardware vendor with the given UUID func (c *Client) DeleteHardwareVendor(id types.UUID) error { _, e := c.HardwareVendor(id.String()).Delete().Send() return e } -func (c *Client) FindOrCreateHardwareVendor(id string) (vendor types.HardwareVendor) { - vendor = c.GetHardwareVendorByID(id) +// FindOrCreateHardwareVendor optionally creates a new hardawre vendor with a +// given name if it does not already exist +func (c *Client) FindOrCreateHardwareVendor(name string) (vendor types.HardwareVendor) { + vendor = c.GetHardwareVendorByName(name) if (vendor == types.HardwareVendor{}) { - c.CreateHardwareVendor(id) - vendor = c.GetHardwareVendorByID(id) + c.CreateHardwareVendor(name) + vendor = c.GetHardwareVendorByName(name) } return } -// POST /hardware_vendor/:hardware_vendor_id_or_name -func (c *Client) CreateHardwareVendor(id string) error { - _, e := c.HardwareVendor(id).Post("").Send() +// CreateHardwareVendor (POST /hardware_vendor/:hardware_vendor_id_or_name) +// createa a new hardware vendor with the given name +func (c *Client) CreateHardwareVendor(name string) error { + _, e := c.HardwareVendor(name).Post("").Send() return e } diff --git a/conch/hardwareVendors_test.go b/conch/hardwareVendors_test.go index c8d1f48..e0ad0e6 100644 --- a/conch/hardwareVendors_test.go +++ b/conch/hardwareVendors_test.go @@ -20,12 +20,12 @@ func TestHardwareVendorRoutes(t *testing.T) { { URL: "/hardware_vendor/", Method: "GET", - Do: func(c *conch.Client) { _ = c.GetHardwareVendors() }, + Do: func(c *conch.Client) { _ = c.GetAllHardwareVendors() }, }, { URL: "/hardware_vendor/foo/", Method: "GET", - Do: func(c *conch.Client) { _ = c.GetHardwareVendorByID("foo") }, + Do: func(c *conch.Client) { _ = c.GetHardwareVendorByName("foo") }, }, { URL: "/hardware_vendor/00000000-0000-0000-0000-000000000000/", diff --git a/conch/organizations.go b/conch/organizations.go index 297b1b9..eb81ecf 100644 --- a/conch/organizations.go +++ b/conch/organizations.go @@ -2,49 +2,57 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /organization -func (c *Client) GetOrganizations() (orgs types.Organizations) { +// GetAllOrganizations (GET /organization) returns the list of organizations +func (c *Client) GetAllOrganizations() (orgs types.Organizations) { c.Organization().Receive(&orgs) return } -// POST /organization +// CreateOrganization (POST /organization) creates a new organization func (c *Client) CreateOrganization(org types.OrganizationCreate) error { _, e := c.Organization().Post(org).Send() return e } -// GET /organization/:organization_id_or_name +// GetOrganizationByName (GET /organization/:organization_id_or_name) retrieves +// an organziation by the given name func (c *Client) GetOrganizationByName(name string) (org types.Organization) { c.Organization(name).Receive(&org) return } -// GET /organization/:organization_id_or_name +// GetOrganizationByID (GET /organization/:organization_id_or_name) retrieves +// an organization by the given UUID func (c *Client) GetOrganizationByID(id types.UUID) (org types.Organization) { c.Organization(id.String()).Receive(&org) return } -// POST /organization/:organization_id_or_name -func (c *Client) UpdateOrganization(id string, update types.OrganizationUpdate) error { - _, e := c.Organization(id).Post(update).Send() +// UpdateOrganization (POST /organization/:organization_id_or_name) updates the +// organzation with the given name +func (c *Client) UpdateOrganization(name string, update types.OrganizationUpdate) error { + _, e := c.Organization(name).Post(update).Send() return e } -// DELETE /organization/:organization_id_or_name +// DeleteOrganization (DELETE /organization/:organization_id_or_name) +// removes the organzation with the given UUID func (c *Client) DeleteOrganization(id types.UUID) error { _, e := c.Organization(id.String()).Delete().Send() return e } -// POST /organization/:organization_id_or_name/user?send_mail=<1|0> +// AddOrganizationUser (POST /organization/:organization_id_or_name/user?send_mail=<1|0>) +// adds a user to the orgaanization with the given UUID. Optionally sends an email to that user. +// BUG(perigrin): sendEmail flag is currently not implemented func (c *Client) AddOrganizationUser(id types.UUID, user types.OrganizationAddUser, sendEmail bool) error { _, e := c.Organization(id.String()).User().Post(user).Send() return e } -// DELETE /organization/:organization_id_or_name/user/#target_user_id_or_email?send_mail=<1|0> +// DeleteOrganizationUser (DELETE /organization/:organization_id_or_name/user/#target_user_id_or_email?send_mail=<1|0>) +// removes a user from the organization with the given ID, optionally sends them an email +// BUG(perigrin): sendEmail flag is currently not implemented func (c *Client) DeleteOrganizationUser(id types.UUID, user string, sendEmail bool) error { _, e := c.Organization(id.String()).User(user).Delete().Send() return e diff --git a/conch/organizations_test.go b/conch/organizations_test.go index 238cf4c..bdd5d03 100644 --- a/conch/organizations_test.go +++ b/conch/organizations_test.go @@ -20,7 +20,7 @@ func TestOrganizationRoutes(t *testing.T) { { URL: "/organization/", Method: "GET", - Do: func(c *conch.Client) { _ = c.GetOrganizations() }, + Do: func(c *conch.Client) { _ = c.GetAllOrganizations() }, }, { URL: "/organization/", diff --git a/conch/rackRoles.go b/conch/rackRoles.go index 67665f6..3901423 100644 --- a/conch/rackRoles.go +++ b/conch/rackRoles.go @@ -2,37 +2,41 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /rack_role +// GetAllRackRoles (GET /rack_role) returns a list of all rack roles func (c *Client) GetAllRackRoles() (roles types.RackRoles) { c.RackRole().Receive(roles) return } -// POST /rack_role +// CreateRackRole (POST /rack_role) creates a new rack role func (c *Client) CreateRackRole(role types.RackRoleCreate) error { _, e := c.RackRole().Post(role).Send() return e } -// GET /rack_role/:rack_role_id_or_name +// GetRackRoleByName (GET /rack_role/:rack_role_id_or_name) +// retrieves the rack role for the given name func (c *Client) GetRackRoleByName(name string) (role types.RackRole) { c.RackRole(name).Receive(role) return } -// GET /rack_role/:rack_role_id_or_name +// GetRackRoleByID (GET /rack_role/:rack_role_id_or_name) retrieves the rack +// role for the given UUID func (c *Client) GetRackRoleByID(id types.UUID) (role types.RackRole) { c.RackRole(id.String()).Receive(role) return } -// POST /rack_role/:rack_role_id_or_name +// UpdateRackRole (POST /rack_role/:rack_role_id_or_name) updates the rack role +// with the given UUID func (c *Client) UpdateRackRole(id types.UUID, update types.RackRoleUpdate) error { _, e := c.RackRole(id.String()).Post(update).Send() return e } -// DELETE /rack_role/:rack_role_id_or_name +// DeleteRackRole (DELETE /rack_role/:rack_role_id_or_name) removes the rack +// role with the given UUID func (c *Client) DeleteRackRole(id types.UUID) error { _, e := c.RackRole(id.String()).Delete().Send() return e diff --git a/conch/racks.go b/conch/racks.go index 1526631..5a80afd 100644 --- a/conch/racks.go +++ b/conch/racks.go @@ -7,111 +7,132 @@ import ( "github.com/joyent/kosh/conch/types" ) -// POST /rack +// CreateRack (POST /rack) creates a new rack func (c *Client) CreateRack(rack types.RackCreate) error { _, e := c.Rack().Post(rack).Send() return e } -// GET /rack/:rack_id_or_name +// GetRackByName (GET /rack/:rack_id_or_name) returns a rack with the given +// name func (c *Client) GetRackByName(name string) (rack types.Rack) { c.Rack(name).Receive(&rack) return } +// GetRackByID (GET /rack/:rack_id_or_name) returns a rack with the given +// UUID func (c *Client) GetRackByID(id types.UUID) (rack types.Rack) { c.Rack(id.String()).Receive(&rack) return } -// POST /rack/:rack_id_or_name +// UpdateRack (POST /rack/:rack_id_or_name) updates a rack with the given UUID func (c *Client) UpdateRack(id types.UUID, rack types.RackUpdate) error { _, e := c.Rack(id.String()).Post(rack).Send() return e } -// DELETE /rack/:rack_id_or_name +// DeleteRack (DELETE /rack/:rack_id_or_name) removes the rack with the given UUID func (c *Client) DeleteRack(id types.UUID) error { _, e := c.Rack(id.String()).Delete().Send() return e } -// GET /rack/:rack_id_or_name/layout +// GetRackLayout (GET /rack/:rack_id_or_name/layout) retrieves the rack layout +// for the rack with the given UUID func (c *Client) GetRackLayout(id types.UUID) (rack types.RackLayouts) { c.Rack(id.String()).Layout().Receive(&rack) return } -// POST /rack/:rack_id_or_name/layout +// UpdateRackLayout (POST /rack/:rack_id_or_name/layout) updates the rack +// layout for the rack with the given UUID func (c *Client) UpdateRackLayout(id types.UUID, layout types.RackLayoutUpdate) error { _, e := c.Rack(id.String()).Layout().Post(layout).Send() return e } +// ReadRackLayoutUpdate takes an io reader and returns a RackLayoutUpdate +// struct suitable for UpdateRackLayout func (c *Client) ReadRackLayoutUpdate(r io.Reader) (update types.RackLayoutUpdate) { json.NewDecoder(r).Decode(&update) return } -// GET /rack/:rack_id_or_name/assignment +// GetRackAssignments (GET /rack/:rack_id_or_name/assignment) gets the current +// assignments for the rack func (c *Client) GetRackAssignments(id types.UUID) (rack types.RackAssignments) { c.Rack(id.String()).Assignment().Receive(&rack) return } -// POST /rack/:rack_id_or_name/assignment +// UpdateRackAssignments (POST /rack/:rack_id_or_name/assignment) updates the +// assignments for the rack func (c *Client) UpdateRackAssignments(id types.UUID, rack types.RackAssignmentUpdates) error { _, e := c.Rack(id.String()).Assignment().Post(rack).Send() return e } +// ReadRackAssignmentUpdate takes an io reader and returns a RackAssignmentUpdates +// struct suitable for UpdateRackAssignments func (c *Client) ReadRackAssignmentUpdate(r io.Reader) (update types.RackAssignmentUpdates) { json.NewDecoder(r).Decode(&update) return } -// DELETE /rack/:rack_id_or_name/assignment +// DeleteRackAssignments (DELETE /rack/:rack_id_or_name/assignment) removes all +// of the current assignments for the rack func (c *Client) DeleteRackAssignments(id types.UUID, deletes types.RackAssignmentDeletes) error { _, e := c.Rack(id.String()).Assignment().Delete(deletes).Send() return e } -// POST /rack/:rack_id_or_name/phase?rack_only=<0|1> +// UpdateRackPhase (POST /rack/:rack_id_or_name/phase?rack_only=<0|1>) updates +// the rack phase and by default all the devices in the rack +// BUG(perigrin): rackOnly currently isn't implemented func (c *Client) UpdateRackPhase(id types.UUID, phase types.RackPhase, rackOnly bool) error { _, e := c.Rack(id.String()).Phase().Post(phase).Send() return e } -// POST /rack/:rack_id_or_name/links +// UpdateRackLinks (POST /rack/:rack_id_or_name/links) updates the links +// associated with the rack func (c *Client) UpdateRackLinks(id types.UUID, links types.RackLinks) error { _, e := c.Rack(id.String()).Links().Post(links).Send() return e } -// DELETE /rack/:rack_id_or_name/links +// DeleteRackLinks (DELETE /rack/:rack_id_or_name/links) removes the links +// associated with the rack func (c *Client) DeleteRackLinks(id types.UUID, phase types.RackLinks) error { _, e := c.Rack(id.String()).Links().Delete().Send() return e } -// GET /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start +// GetSingleRackLayoutByRU (GET /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// returns a single layout for the given RU func (c *Client) GetSingleRackLayoutByRU(id types.UUID, ru string) (rack types.RackLayout) { c.Rack(id.String()).Layout(ru).Receive(&rack) return } +// GetSingleRackLayoutByID (GET /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// returns a single layout for the given UUID func (c *Client) GetSingleRackLayoutByID(rackID, layoutID types.UUID) (rack types.RackLayout) { c.Rack(rackID.String()).Layout(layoutID.String()).Receive(&rack) return } -// POST /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start +// UpdateSingleRackLayout (POST /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// updates a single rack layout with the given UUID func (c *Client) UpdateSingleRackLayout(rackID, layoutID types.UUID, update types.RackLayoutUpdate) error { _, e := c.Rack(rackID.String()).Layout(layoutID.String()).Post(update).Send() return e } -// DELETE /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start +// DeleteSingleRackLayout (DELETE /rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// removes the rack layout with the given UUID func (c *Client) DeleteSingleRackLayout(rackID types.UUID, layoutID types.UUID) error { _, e := c.Rack(rackID.String()).Layout(layoutID.String()).Delete().Send() return e diff --git a/conch/relays.go b/conch/relays.go index 99a64f0..6d7c63b 100644 --- a/conch/relays.go +++ b/conch/relays.go @@ -2,30 +2,34 @@ package conch import "github.com/joyent/kosh/conch/types" -// POST /relay/:relay_serial_number/register -func (c *Client) RegisterRelay(id string, relay types.RegisterRelay) error { - _, e := c.Relay(id).Register().Post(relay).Send() +// RegisterRelay (POST /relay/:relay_serial_number/register) +// registers a relay with the given serial number +func (c *Client) RegisterRelay(serial string, relay types.RegisterRelay) error { + _, e := c.Relay(serial).Register().Post(relay).Send() return e } -// GET /relay +// GetAllRelays (GET /relay) returns a list of all relays func (c *Client) GetAllRelays() (relays types.Relays) { c.Relay().Receive(&relays) return } -// GET /relay/:relay_id_or_serial_number +// GetRelayBySerial (GET /relay/:relay_id_or_serial_number) retrieves a relay +// with the given serial number func (c *Client) GetRelayBySerial(serial string) (relay types.Relay) { c.Relay(serial).Receive(&relay) return } +// GetRelayByID (GET /relay/:relay_id_or_serial_number) retrieves a relay +// with the given UUID func (c *Client) GetRelayByID(id types.UUID) (relay types.Relay) { c.Relay(id.String()).Receive(&relay) return } -// DELETE /relay/:relay_id_or_serial_number +// DeleteRelay (DELETE /relay/:relay_id_or_serial_number) removes a relay func (c *Client) DeleteRelay(id string) error { _, e := c.Relay(id).Delete().Send() return e diff --git a/conch/rooms.go b/conch/rooms.go index 07037e8..07952ff 100644 --- a/conch/rooms.go +++ b/conch/rooms.go @@ -2,136 +2,160 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /room +// GetAllRooms (GET /room) returns a list of all datacenter rooms func (c *Client) GetAllRooms() (rooms types.DatacenterRoomsDetailed) { c.Room().Receive(rooms) return } -// POST /room +// CreateRoom (POST /room) creates a new datacenter room func (c *Client) CreateRoom(room types.DatacenterRoomCreate) error { _, e := c.Room().Post(room).Send() return e } -// GET /room/:datacenter_room_id_or_alias +// GetRoomByAlias (GET /room/:datacenter_room_id_or_alias) retrieves the +// datacenter room with the given alias func (c *Client) GetRoomByAlias(alias string) (room types.DatacenterRoomDetailed) { c.Room(alias).Receive(room) return } +// GetRoomByID (GET /room/:datacenter_room_id_or_alias) retrieves the +// datacenter room with the given UUID func (c *Client) GetRoomByID(id types.UUID) (room types.DatacenterRoomDetailed) { c.Room(id.String()).Receive(room) return } -// POST /room/:datacenter_room_id_or_alias +// UpdateRoom (POST /room/:datacenter_room_id_or_alias) +// updates the datacenter room with the given UUID func (c *Client) UpdateRoom(id types.UUID, room types.DatacenterRoomUpdate) error { _, e := c.Room(id.String()).Post(room).Send() return e } -// DELETE /room/:datacenter_room_id_or_alias +// DeleteRoom (DELETE /room/:datacenter_room_id_or_alias) +// removes the datacenter room with the given UUID func (c *Client) DeleteRoom(id types.UUID) error { _, e := c.Room(id.String()).Delete().Send() return e } -// GET /room/:datacenter_room_id_or_alias/rack +// GetAllRoomRacks (GET /room/:datacenter_room_id_or_alias/rack) +// returns a list of all racks in the room with the given UUID func (c *Client) GetAllRoomRacks(id types.UUID) (racks types.Racks) { c.Room(id.String()).Rack().Receive(racks) return } -// GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name +// GetRoomRackByName (GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name) +// returns the specific rack with the given name in the room with the given UUID func (c *Client) GetRoomRackByName(id types.UUID, name string) (rack types.Rack) { c.Room(id.String()).Rack(name).Receive(rack) return } +// GetRoomRackByID (GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name) +// returns the specific rack with the given UUID in the room with the given UUID func (c *Client) GetRoomRackByID(roomID, rackID types.UUID) (rack types.Rack) { c.Room(roomID.String()).Rack(rackID.String()).Receive(rack) return } -// POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name +// UpdateRoomRack (POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name) +// update the rack with the given UUID in the room with the given UUID func (c *Client) UpdateRoomRack(roomID, rackID types.UUID, rack types.RackUpdate) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Post(rack).Send() return e } -// DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name +// DeleteRoomRack (DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name) +// remove the rack with the given UUID in the room with the given UUID func (c *Client) DeleteRoomRack(roomID, rackID types.UUID) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Delete().Send() return e } -// GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout +// GetRoomRackLayout (GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout) +// get the rack layout for the rack in the given room func (c *Client) GetRoomRackLayout(roomID, rackID types.UUID) (rack types.RackLayouts) { c.Room(roomID.String()).Rack(roomID.String()).Layout().Receive(rack) return } -// POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout +// UpdateRoomRackLayout (POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout) +// update the rack layout for the rack in the room func (c *Client) UpdateRoomRackLayout(roomID, rackID types.UUID, layout types.RackLayoutUpdate) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Layout().Post(layout).Send() return e } -// GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/assignment +// GetRoomRackAssignments (GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/assignment) +// retrieve the rack assignments for the rack in the given room func (c *Client) GetRoomRackAssignments(roomID, rackID types.UUID) (rack types.RackAssignments) { c.Room(roomID.String()).Rack(rackID.String()).Assignment().Receive(rack) return } -// POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/assignment +// UpdateRoomRackAssignments (POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/assignment) +// update the rack assignments for the rack in the given room func (c *Client) UpdateRoomRackAssignments(roomID, rackID types.UUID, rack types.RackAssignmentUpdates) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Assignment().Post(rack).Send() return e } -// DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/assignment +// DeleteRoomRackAssignments (DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/assignment) +// remove the rack assignments for the rack in the given room func (c *Client) DeleteRoomRackAssignments(roomID, rackID types.UUID, deletes types.RackAssignmentDeletes) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Assignment().Delete(deletes).Send() return e } -// POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/phase?rack_only=<0|1> +// UpdateRoomRackPhase (POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/phase?rack_only=<0|1>) +// update the rack phase for the rack in the given room func (c *Client) UpdateRoomRackPhase(roomID, rackID types.UUID, phase types.RackPhase, rackOnly bool) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Phase().Post(phase).Send() return e } -// POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/links +// UpdateRoomRackLinks (POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/links) +// update the rack links for the rack in the given room func (c *Client) UpdateRoomRackLinks(roomID, rackID types.UUID, links types.RackLinks) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Links().Post(links).Send() return e } -// DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/links +// DeleteRoomRackLinks (DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/links) +// remove the rack links for the rack in the given room func (c *Client) DeleteRoomRackLinks(roomID, rackID types.UUID, phase types.RackLinks) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Links().Delete().Send() return e } -// GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start +// GetSingleRoomRackLayoutByRU (GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// get the rack layout for a single named RU in a rack in a room func (c *Client) GetSingleRoomRackLayoutByRU(roomID, rackID types.UUID, ru string) (rack types.RackLayout) { c.Room(roomID.String()).Rack(rackID.String()).Layout(ru).Receive(rack) return } +// GetSingleRoomRackLayoutByID (GET /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// get the rack layout for given UUID in a rack in a room func (c *Client) GetSingleRoomRackLayoutByID(roomID, rackID, layoutID types.UUID) (rack types.RackLayout) { c.Room(rackID.String()).Rack(rackID.String()).Layout(layoutID.String()).Receive(rack) return } -// POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start +// UpdateSingleRoomRackLayout (POST /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// update the rack layout for given UUID in a rack in a room func (c *Client) UpdateSingleRoomRackLayout(roomID, rackID, layoutID types.UUID, update types.RackLayoutUpdate) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Layout(layoutID.String()).Post(update).Send() return e } -// DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start +// DeleteSingleRoomRackLayout (DELETE /room/:datacenter_room_id_or_alias/rack/:rack_id_or_name/layout/:layout_id_or_rack_unit_start) +// remove the rack layout for given UUID in a rack in a room func (c *Client) DeleteSingleRoomRackLayout(roomID, rackID, layoutID types.UUID) error { _, e := c.Room(roomID.String()).Rack(rackID.String()).Layout(layoutID.String()).Delete().Send() return e diff --git a/conch/schema.go b/conch/schema.go index debeeb7..4acdbe7 100644 --- a/conch/schema.go +++ b/conch/schema.go @@ -4,7 +4,9 @@ import ( "github.com/qri-io/jsonschema" ) -func (c *Client) GetSchema(name string) (schema jsonschema.Schema) { - c.Schema(name).Receive(&schema) +// GetSchema (GET /json_schema) retieves the json-schema defined with the given +// path (/common/:name, /request/:name, /response/:name) +func (c *Client) GetSchema(path string) (schema jsonschema.Schema) { + c.Schema(path).Receive(&schema) return } diff --git a/conch/users.go b/conch/users.go index 5d751cd..cb42bbc 100644 --- a/conch/users.go +++ b/conch/users.go @@ -2,132 +2,163 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /user/me +// GetCurrentUser (GET /user/me) retrieves the user associated with the current +// authentication func (c *Client) GetCurrentUser() (me types.UserDetailed) { - c.Debug("GetCurrentUser()") - me = c.GetUserByID("me") + me = c.GetUserByEmail("me") return } -// POST /user/me/revoke +// RevokeCurrentUserCredentials (POST /user/me/revoke) reokes the +// authentication (login) credentials for the current user. +// DOES NOT AFFECT API TOKENS func (c *Client) RevokeCurrentUserCredentials() error { return c.RevokeUserCredentials("me") } -// POST /user/me/password +// ChangeCurrentUserPassword (POST /user/me/password) +// updates the password for the current user func (c *Client) ChangeCurrentUserPassword(setting types.UserSetting) error { return c.ChangeUserPassword("me", setting) } -// GET /user/me/settings +// GetCurrentUserSettings (GET /user/me/settings) gets the settings for the +// current user func (c *Client) GetCurrentUserSettings() (settings types.UserSettings) { c.User("me").Settings("").Receive(&settings) return } -// POST /user/me/setting +// SetCurrentUserSettings (POST /user/me/setting) updates the settings for the +// current user func (c *Client) SetCurrentUserSettings(settings types.UserSettings) error { _, e := c.User("me").Settings().Post(settings).Send() return e } -// GET /user/me/setting/:name +// GetCurrentUserSettingByName (GET /user/me/setting/:name) retrieves a single +// user setting func (c *Client) GetCurrentUserSettingByName(name string) (setting types.UserSetting) { c.User("me").Settings(name).Receive(&setting) return } -// POST /user/me/setting/:name +// SetCurrentUserSettingByName (POST /user/me/setting/:name) sets a single +// users setting func (c *Client) SetCurrentUserSettingByName(name string, setting types.UserSetting) error { _, e := c.User("me").Settings(name).Post(setting).Send() return e } -// DELETE /user/me/setting/:name +// DeleteCurrentUserSetting (DELETE /user/me/setting/:name) removes a single +// user setting by name func (c *Client) DeleteCurrentUserSetting(name string) error { _, e := c.User("me").Settings(name).Delete().Send() return e } -// GET /user/me/token +// GetCurrentUserTokens (GET /user/me/token) returns the list of API tokens for the current user func (c *Client) GetCurrentUserTokens() (tokens types.UserTokens) { - tokens = c.GetUserToken("me") + tokens = c.GetUserTokens("me") return } -// POST /user/me/token +// CreateCurrentUserToken (POST /user/me/token) creates a new API token for the +// current user. This is the only time the actual token string will be readable func (c *Client) CreateCurrentUserToken(newToken types.NewUserToken) (token types.NewUserToken) { c.User("me").Token().Post(newToken).Receive(&token) return } -// GET /user/me/token/:token_name +// GetCurrentUserTokenByName (GET /user/me/token/:token_name) returns the +// information for a single API token for the current user. The token string +// itself is not readable. func (c *Client) GetCurrentUserTokenByName(name string) (token types.UserToken) { token = c.GetUserTokenByName("me", name) return } -// DELETE /user/me/token/:token_name +// DeleteCurrentUserToken (DELETE /user/me/token/:token_name) removes the token +// with the given name for the current user func (c *Client) DeleteCurrentUserToken(name string) error { return c.DeleteUserToken("me", name) } -// GET /user/:target_user_id_or_email -func (c *Client) GetUserByID(id string) (user types.UserDetailed) { - c.User(id).Receive(&user) +// GetUserByEmail (GET /user/:target_user_id_or_email) retrieves the user with +// the given email +func (c *Client) GetUserByEmail(email string) (user types.UserDetailed) { + c.User(email).Receive(&user) return } -// POST /user/:target_user_id_or_email?send_mail=<1|0> -func (c *Client) UpdateUser(id string, update types.UpdateUser) error { - _, e := c.User(id).Post(update).Send() +// GetUserByID (GET /user/:target_user_id_or_email) retrieves the user with +// the given UUID +func (c *Client) GetUserByID(id types.UUID) (user types.UserDetailed) { + c.User(id.String()).Receive(&user) + return +} + +// UpdateUser (POST /user/:target_user_id_or_email?send_mail=<1|0>) will update the +// user with the given email. Optionally notify the user via email. +// BUG(perigrin): sendEmail is currently not implemented +func (c *Client) UpdateUser(email string, update types.UpdateUser, sendEmail bool) error { + _, e := c.User(email).Post(update).Send() return e } -// DELETE /user/:target_user_id_or_email -func (c *Client) DeleteUser(id string) error { - _, e := c.User(id).Delete().Send() +// DeleteUser (DELETE /user/:target_user_id_or_email) will remove the user with the +// given email +func (c *Client) DeleteUser(email string) error { + _, e := c.User(email).Delete().Send() return e } -// POST /user/:target_user_id_or_email/revoke -func (c *Client) RevokeUserCredentials(id string) error { - _, e := c.User(id).Revoke().Post("").Send() +// RevokeUserCredentials (POST /user/:target_user_id_or_email/revoke) will +// revoke the authentication credentials for the user with hte given email. +// DOES NOT AFFECT API TOKENS FOR THE USER +func (c *Client) RevokeUserCredentials(email string) error { + _, e := c.User(email).Revoke().Post("").Send() return e } -// DELETE /user/:target_user_id_or_email/password -func (c *Client) ChangeUserPassword(id string, setting types.UserSetting) error { - _, e := c.User(id).Password().Post(setting).Send() +// ChangeUserPassword (DELETE /user/:target_user_id_or_email/password) triggers +// the password change mechanisim for the user with the given email. +func (c *Client) ChangeUserPassword(email string, setting types.UserSetting) error { + _, e := c.User(email).Password().Post(setting).Send() return e } -// GET /user -func (c *Client) GetUsers() (me types.UsersDetailed) { +// GetAllUsers (GET /user) retrieves a list of all users +func (c *Client) GetAllUsers() (me types.UsersDetailed) { c.User("").Receive(&me) return } -// POST /user?send_mail=<1|0> -func (c *Client) CreateUser(newUser types.NewUser) (user types.NewUser) { +// CreateUser (POST /user?send_mail=<1|0>) create a new user in teh system and +// optionally send them an email notification. +// BUG(perigrin): sendEmail isn't implemented +func (c *Client) CreateUser(newUser types.NewUser, sendEmail bool) (user types.NewUser) { c.User().Post(newUser).Receive(&user) return } -// GET /user/:target_user_id_or_email/token -func (c *Client) GetUserToken(id string) (tokens types.UserTokens) { - c.User(id).Token().Receive(&tokens) +// GetUserTokens (GET /user/:target_user_id_or_email/token) retrieves the list +// of API tokens for the given user. +func (c *Client) GetUserTokens(email string) (tokens types.UserTokens) { + c.User(email).Token().Receive(&tokens) return } -// GET /user/:target_user_id_or_email/token/:token_name -func (c *Client) GetUserTokenByName(id, name string) (token types.UserToken) { - c.User(id).Token(name).Receive(&token) +// GetUserTokenByName (GET /user/:target_user_id_or_email/token/:token_name) +// retrieves a single named API token for the given user +func (c *Client) GetUserTokenByName(email, name string) (token types.UserToken) { + c.User(email).Token(name).Receive(&token) return } -// DELETE /user/:target_user_id_or_email/token/:token_name -func (c *Client) DeleteUserToken(id, name string) error { - _, e := c.User(id).Token(name).Delete().Send() +// DeleteUserToken (DELETE /user/:target_user_id_or_email/token/:token_name) +// removes a named API token for the given user +func (c *Client) DeleteUserToken(email, name string) error { + _, e := c.User(email).Token(name).Delete().Send() return e } diff --git a/conch/users_test.go b/conch/users_test.go index 3f1cc20..4673c1f 100644 --- a/conch/users_test.go +++ b/conch/users_test.go @@ -75,14 +75,19 @@ func TestUser(t *testing.T) { Do: func(c *conch.Client) { _ = c.DeleteCurrentUserToken("foo") }, }, { - URL: "/user/foo/", + URL: "/user/foo@example.com/", Method: "GET", - Do: func(c *conch.Client) { _ = c.GetUserByID("foo") }, + Do: func(c *conch.Client) { _ = c.GetUserByEmail("foo@example.com") }, + }, + { + URL: "/user/foo/", + Method: "POST", + Do: func(c *conch.Client) { _ = c.UpdateUser("foo", types.UpdateUser{}, false) }, }, { URL: "/user/foo/", Method: "POST", - Do: func(c *conch.Client) { _ = c.UpdateUser("foo", types.UpdateUser{}) }, + Do: func(c *conch.Client) { _ = c.UpdateUser("foo", types.UpdateUser{}, true) }, }, { URL: "/user/foo/", @@ -104,17 +109,23 @@ func TestUser(t *testing.T) { { URL: "/user/", Method: "GET", - Do: func(c *conch.Client) { _ = c.GetUsers() }, + Do: func(c *conch.Client) { _ = c.GetAllUsers() }, }, { URL: "/user/", Method: "POST", - Do: func(c *conch.Client) { _ = c.CreateUser(types.NewUser{}) }, + Do: func(c *conch.Client) { _ = c.CreateUser(types.NewUser{}, false) }, }, + { + URL: "/user/", + Method: "POST", + Do: func(c *conch.Client) { _ = c.CreateUser(types.NewUser{}, true) }, + }, + { URL: "/user/foo/token/", Method: "GET", - Do: func(c *conch.Client) { _ = c.GetUserToken("foo") }, + Do: func(c *conch.Client) { _ = c.GetUserTokens("foo") }, }, { URL: "/user/foo/token/bar/", diff --git a/conch/validations.go b/conch/validations.go index 04dce2e..9121a51 100644 --- a/conch/validations.go +++ b/conch/validations.go @@ -2,52 +2,68 @@ package conch import "github.com/joyent/kosh/conch/types" -// GET /validation +// GetValidations ( GET /validation ) returns a list of all validations from +// the server. See also +// https://joyent.github.io/conch-api/modules/Conch%3A%3ARoute%3A%3AValidation#get-validations func (c *Client) GetValidations() (validations types.Validations) { c.Validation().Receive(&validations) return } -// GET /validation/:validation_id_or_name +// GetValidationByName (GET /validation/:validation_id_or_name ) returns a single +// validation from the server for the given string. See also +// https://joyent.github.io/conch-api/modules/Conch%3A%3ARoute%3A%3AValidation#get-validation func (c *Client) GetValidationByName(name string) (validation types.Validation) { c.Validation(name).Receive(&validation) return } +// GetValidationByID (GET /validation/:validation_id_or_name ) returns a single +// validation from the server for the given UUID. See also +// https://joyent.github.io/conch-api/modules/Conch%3A%3ARoute%3A%3AValidation#get-validation func (c *Client) GetValidationByID(id types.UUID) (validation types.Validation) { c.Validation(id.String()).Receive(&validation) return } -// GET /validation_plan +// GetAllValidationPlans ( GET /validation_plan ) returns a list of all +// validations plans. See also +// https://joyent.github.io/conch-api/modules/Conch%3A%3ARoute%3A%3AValidation#get-validation_plans func (c *Client) GetAllValidationPlans() (plans types.ValidationPlans) { c.ValidationPlan().Receive(&plans) return } -// GET /validation_plan/:validation_plan_id_or_name +// GetValidationPlanByName (GET /validation_plan/:validation_plan_id_or_name) +// retrieves a single validation plan with the given name func (c *Client) GetValidationPlanByName(name string) (plan types.ValidationPlan) { c.ValidationPlan(name).Receive(&plan) return } +// GetValidationPlanByID (GET /validation_plan/:validation_plan_id_or_name) +// retrieves a single validation plan with the given UUID func (c *Client) GetValidationPlanByID(id types.UUID) (plan types.ValidationPlan) { c.ValidationPlan(id.String()).Receive(&plan) return } -// GET /validation_plan/:validation_plan_id_or_name/validation -func (c *Client) GetValidationPlanValidations(id string) (validations types.Validations) { - c.ValidationPlan(id).Validation().Receive(&validations) +// GetValidationPlanValidations (GET /validation_plan/:validation_plan_id_or_name/validation) +// get the list of validations for the named validation plan +func (c *Client) GetValidationPlanValidations(name string) (validations types.Validations) { + c.ValidationPlan(name).Validation().Receive(&validations) return } -// GET /validation_state/:validation_state_id_or_name +// GetValidationStateByName (GET /validation_state/:validation_state_id_or_name) +// retrieves the validation state with the given name func (c *Client) GetValidationStateByName(name string) (state types.ValidationStateWithResults) { c.ValidationState(name).Receive(&state) return } +// GetValidationStateByID (GET /validation_state/:validation_state_id_or_name) +// retrieves the validation state with the given UUID func (c *Client) GetValidationStateByID(id types.UUID) (state types.ValidationStateWithResults) { c.ValidationState(id.String()).Receive(&state) return diff --git a/logger/logger.go b/logger/logger.go index b917f52..54d183d 100644 --- a/logger/logger.go +++ b/logger/logger.go @@ -1,3 +1,8 @@ +/* +Package logger is a simple logging module based upon the advice of Dave Cheney + * https://dave.cheney.net/2015/11/05/lets-talk-about-logging + * https://dave.cheney.net/2017/01/23/the-package-level-logger-anti-pattern +*/ package logger import ( @@ -7,18 +12,25 @@ import ( "net/http/httputil" ) +// Interface is the default interface for logging with this logger. Debug() is +// for developer targeted output. While Info is for (verbose) user targeted +// output. type Interface interface { Deubg(...interface{}) Info(...interface{}) } +// Logger is the default logger with configuration levels for debug (developer) +// output, and info (verbose user) output. type Logger struct { LevelDebug bool LevelInfo bool } +// New returns a new instance of the Logger struct func New() Logger { return Logger{} } +// Debug outputs developer targeted messaging. func (l Logger) Debug(messages ...interface{}) { if l.LevelDebug { for _, m := range messages { @@ -46,6 +58,7 @@ func (l Logger) Debug(messages ...interface{}) { } } +// Info outputs more verbose user targed information func (l Logger) Info(messages ...interface{}) { if l.LevelInfo { for _, m := range messages { diff --git a/tables/tables.go b/tables/tables.go index 04bd787..721248e 100644 --- a/tables/tables.go +++ b/tables/tables.go @@ -1,3 +1,6 @@ +/* +Package tables renders tabular data. +*/ package tables import ( @@ -8,24 +11,30 @@ import ( "github.com/olekukonko/tablewriter" ) +// NewTable returns a pointer to a configured instance of tableWriter.Table func NewTable(writer io.Writer) *tablewriter.Table { table := tablewriter.NewWriter(writer) TableToMarkdown(table) return table } +// TableToMarkdown sets the table up to render in a markdown compatible format func TableToMarkdown(table *tablewriter.Table) { table.SetAutoWrapText(false) table.SetBorders(tablewriter.Border{Left: true, Top: false, Right: true, Bottom: false}) table.SetCenterSeparator("|") } +// Tabulable is an interface for any structure that can be rendered into a +// table form type Tabulable interface { Headers() []string ForEach(func([]string)) sort.Interface } +// Render takess a Tabulable struct and renders it into markdown compatible +// string func Render(list Tabulable) string { sort.Sort(list) diff --git a/template/template.go b/template/template.go index c33ee7c..c0efe18 100644 --- a/template/template.go +++ b/template/template.go @@ -1,3 +1,7 @@ +/* +Package template provies utilities for rendering the output to markdown +compatible output +*/ package template import ( @@ -21,7 +25,7 @@ func CutUUID(id string) string { return id } -// TimeStr fformats a time value into something human readable +// TimeStr formats a time value into something human readable func TimeStr(t time.Time) string { if t.IsZero() { return "" @@ -29,6 +33,7 @@ func TimeStr(t time.Time) string { return t.Local().Format(dateFormat) } +// Table formats Tabulable data using the tables package func Table(t tables.Tabulable) string { return tables.Render(t) } @@ -42,11 +47,12 @@ func NewTemplate() *template.Template { }) } +// Templated tracks what the template is for a given data structure type Templated interface { Template() string } -// Render takes a struct, and a template string and returns a string +// Render takes a Templated datapiecea and returns a markdown compatible string func Render(data Templated) (string, error) { template := data.Template() t, err := NewTemplate().Parse(template)