oxide: refactor exported client API

.changelog/v0.1.0-beta3.toml

@@ -11,5 +11,13 @@ title = ""
 description = ""
 
 [[breaking]]
-title = "Go verrsion"
-description = "Minimum required Go version has been updated to 1.21. [#179](https://github.com/oxidecomputer/oxide.go/pull/179)"
+title = "Go version"
+description = "Minimum required Go version has been updated to 1.21. [#179](https://github.com/oxidecomputer/oxide.go/pull/179)"
+
+[[breaking]]
+title = "NewClient API change"
+description = "The `NewClient` function has been updated to no longer require a user agent parameter. [#180](https://github.com/oxidecomputer/oxide.go/pull/180)"
+
+[[breaking]]
+title = "NewClientFromEnv removal"
+description = "The `NewClientFromEnv` function has been removed. Users should use `NewClient` instead. [#180](https://github.com/oxidecomputer/oxide.go/pull/180)"

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -11,7 +11,9 @@ labels: release
  After completing each task put an `x` in the corresponding box,
  and paste the link to the relevant PR.
 -->
-- [ ] Make sure version is set to the new version in `VERSION` file.
+- [ ] Make sure the following files have the new version you want to release.
+  - [ ] [`VERSION`](./VERSION)
+  - [ ] [`oxide/version.go`](./oxide/version.go)
 - [ ] Make sure all examples and docs reference the new version.
 - [ ] Generate changelog by running `make changelog` and add date of the release to the title.
 - [ ] Release the new version by running `make tag`.

CONTRIBUTING.md

@@ -14,7 +14,9 @@ $ make all
 
 ## Releasing a new SDK version
 
-1. Make sure the [`VERSION`](./VERSION) file has the new version you want to release.
+1. Make sure the following files have the new version you want to release.
+  1. [`VERSION`](./VERSION)
+  1. [`oxide/version.go`](./oxide/version.go)
 2. Make sure you have run `make all` and pushed any changes. The release
    will fail if running `make all` causes any changes to the generated
    code.

README.md

@@ -32,7 +32,11 @@ import (
 )
 
 func main() {
-	client, err := oxide.NewClient("<auth token>", "<user-agent>", "<host>")
+	cfg := oxide.Config{
+		Address: "https://api.oxide.computer",
+		Token:   "oxide-abc123",
+	}
+	client, err := oxide.NewClient(&cfg)
 	if err != nil {
 		panic(err)
 	}

internal/generate/templates/no_resptype_body_method.tpl

@@ -10,7 +10,7 @@
     b := params.Body{{end}}
 
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         b, 
         "{{.HTTPMethod}}", 

internal/generate/templates/no_resptype_method.tpl

@@ -3,7 +3,7 @@
 		return err
 	}{{end}}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "{{.HTTPMethod}}", 

internal/generate/templates/resptype_body_method.tpl

@@ -10,7 +10,7 @@
     b := params.Body{{end}}
 
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         b, 
         "{{.HTTPMethod}}", 

internal/generate/templates/resptype_method.tpl

@@ -3,7 +3,7 @@
 		return nil, err
 	}{{end}}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "{{.HTTPMethod}}", 

internal/generate/test_utils/paths_output

@@ -14,7 +14,7 @@ func (c *Client) IpPoolList(ctx context.Context, params IpPoolListParams, ) (*Ip
 		return nil, err
 	}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "GET", 
@@ -95,7 +95,7 @@ func (c *Client) IpPoolCreate(ctx context.Context, params IpPoolCreateParams, )
     }
 
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         b, 
         "POST", 
@@ -141,7 +141,7 @@ func (c *Client) IpPoolView(ctx context.Context, params IpPoolViewParams, ) (*Ip
 		return nil, err
 	}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "GET", 
@@ -194,7 +194,7 @@ func (c *Client) IpPoolUpdate(ctx context.Context, params IpPoolUpdateParams, )
     }
 
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         b, 
         "PUT", 
@@ -241,7 +241,7 @@ func (c *Client) IpPoolDelete(ctx context.Context, params IpPoolDeleteParams, )
 		return err
 	}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "DELETE", 

internal/generate/test_utils/paths_output_expected

@@ -14,7 +14,7 @@ func (c *Client) IpPoolList(ctx context.Context, params IpPoolListParams, ) (*Ip
 		return nil, err
 	}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "GET", 
@@ -95,7 +95,7 @@ func (c *Client) IpPoolCreate(ctx context.Context, params IpPoolCreateParams, )
     }
 
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         b, 
         "POST", 
@@ -141,7 +141,7 @@ func (c *Client) IpPoolView(ctx context.Context, params IpPoolViewParams, ) (*Ip
 		return nil, err
 	}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "GET", 
@@ -194,7 +194,7 @@ func (c *Client) IpPoolUpdate(ctx context.Context, params IpPoolUpdateParams, )
     }
 
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         b, 
         "PUT", 
@@ -241,7 +241,7 @@ func (c *Client) IpPoolDelete(ctx context.Context, params IpPoolDeleteParams, )
 		return err
 	}
     // Create the request
-    req, err := buildRequest(
+    req, err := c.buildRequest(
         ctx,
         nil, 
         "DELETE", 

oxide/lib.go

@@ -22,75 +22,98 @@ const TokenEnvVar = "OXIDE_TOKEN"
 // HostEnvVar is the environment variable that contains the host.
 const HostEnvVar = "OXIDE_HOST"
 
+// Config is the configuration that can be set on a Client.
+type Config struct {
+	// Base URL of the Oxide API including the scheme. For example,
+	// https://api.oxide.computer.
+	Address string
+
+	// Oxide API authentication token.
+	Token string
+
+	// A custom HTTP client to use for the Client instead of the default.
+	HTTPClient *http.Client
+
+	// A custom user agent string to add to every request instead of the
+	// default.
+	UserAgent string
+}
+
 // Client which conforms to the OpenAPI3 specification for this service.
 type Client struct {
-	// The endpoint of the server conforming to this interface, with scheme,
-	// https://api.oxide.computer for example.
+	// Base URL of the Oxide API including the scheme. For example,
+	// https://api.oxide.computer.
 	server string
 
-	// Client is the *http.Client for performing requests.
+	// Oxide API authentication token.
+	token string
+
+	// HTTP client to make API requests.
 	client *http.Client
 
-	// token is the API token used for authentication.
-	token string
+	// The user agent string to add to every API request.
+	userAgent string
 }
 
-// NewClient creates a new client for the Oxide API.
-// You need to pass in your API token to create the client.
-func NewClient(token, userAgent, host string) (*Client, error) {
-	if token == "" {
-		return nil, fmt.Errorf("you need to pass in an API token to create the client")
+// NewClient creates a new client for the Oxide API. Pass in a non-nil *Config
+// to set the various configuration options on a Client.
+func NewClient(cfg *Config) (*Client, error) {
+	token := os.Getenv(TokenEnvVar)
+	server := os.Getenv(HostEnvVar)
+	userAgent := defaultUserAgent()
+	httpClient := &http.Client{
+		Timeout: 600 * time.Second,
 	}
 
-	baseURL, err := parseBaseURL(host)
-	if err != nil {
-		return nil, err
-	}
+	// Layer in the user-provided configuration if provided.
+	if cfg != nil {
+		if cfg.Address != "" {
+			server = cfg.Address
+		}
 
-	client := &Client{
-		server: baseURL,
-		token:  token,
-	}
+		if cfg.Token != "" {
+			token = cfg.Token
+		}
 
-	// Ensure the server URL always has a trailing slash.
-	if !strings.HasSuffix(client.server, "/") {
-		client.server += "/"
-	}
+		if cfg.UserAgent != "" {
+			userAgent = cfg.UserAgent
+		}
 
-	uat := userAgentTransport{
-		base:      http.DefaultTransport,
-		userAgent: userAgent,
-		client:    client,
+		if cfg.HTTPClient != nil {
+			httpClient = cfg.HTTPClient
+		}
 	}
 
-	client.client = &http.Client{
-		Transport: uat,
-		// We want a longer timeout since some of the files might take a bit.
-		Timeout: 600 * time.Second,
+	server, err := parseBaseURL(server)
+	if err != nil {
+		return nil, fmt.Errorf("failed parsing client address: %w", err)
 	}
 
-	return client, nil
-}
-
-// NewClientFromEnv creates a new client for the Oxide API, using the token
-// stored in the environment variable `OXIDE_TOKEN` and the host stored in the
-// environment variable `OXIDE_HOST`.
-func NewClientFromEnv(userAgent string) (*Client, error) {
-	token := os.Getenv(TokenEnvVar)
 	if token == "" {
-		return nil, fmt.Errorf("the environment variable %s must be set with your API token", TokenEnvVar)
+		return nil, errors.New("invalid client configuration: token is required")
 	}
 
-	host := os.Getenv(HostEnvVar)
-	if host == "" {
-		return nil, fmt.Errorf("the environment variable %s must be set with the host of the Oxide API", HostEnvVar)
+	client := &Client{
+		token:     token,
+		server:    server,
+		userAgent: userAgent,
+		client:    httpClient,
 	}
 
-	return NewClient(token, userAgent, host)
+	return client, nil
+}
+
+// defaultUserAgent builds and returns the default user agent string.
+func defaultUserAgent() string {
+	return fmt.Sprintf("oxide.go/%s", version)
 }
 
 // parseBaseURL parses the base URL from the server URL.
 func parseBaseURL(baseURL string) (string, error) {
+	if baseURL == "" {
+		return "", errors.New("address is empty")
+	}
+
 	if !strings.HasPrefix(baseURL, "http://") && !strings.HasPrefix(baseURL, "https://") {
 		// Assume https.
 		baseURL = "https://" + baseURL
@@ -111,47 +134,21 @@ func parseBaseURL(baseURL string) (string, error) {
 	return b, nil
 }
 
-// WithToken overrides the token used for authentication.
-func (c *Client) WithToken(token string) {
-	c.token = token
-}
-
-type userAgentTransport struct {
-	userAgent string
-	base      http.RoundTripper
-	client    *Client
-}
-
-func (t userAgentTransport) RoundTrip(req *http.Request) (*http.Response, error) {
-	if t.base == nil {
-		return nil, errors.New("RoundTrip: no Transport specified")
-	}
-
-	newReq := *req
-	newReq.Header = make(http.Header)
-	for k, vv := range req.Header {
-		newReq.Header[k] = vv
-	}
-
-	// Add the user agent header.
-	newReq.Header["User-Agent"] = []string{t.userAgent}
-
-	// Add the content-type header.
-	newReq.Header["Content-Type"] = []string{"application/json"}
-
-	// Add the authorization header.
-	newReq.Header["Authorization"] = []string{fmt.Sprintf("Bearer %s", t.client.token)}
-
-	return t.base.RoundTrip(&newReq)
-}
-
-func buildRequest(ctx context.Context, body io.Reader, method, uri string, params, queries map[string]string) (*http.Request, error) {
+// buildRequest creates an HTTP request to interact with the Oxide API.
+func (c *Client) buildRequest(ctx context.Context, body io.Reader, method, uri string, params, queries map[string]string) (*http.Request, error) {
 	// Create the request.
 	req, err := http.NewRequestWithContext(ctx, method, uri, body)
 	if err != nil {
 		return nil, fmt.Errorf("error creating request: %v", err)
 	}
 
+	if c.userAgent != "" {
+		req.Header.Set("User-Agent", c.userAgent)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", c.token)
+
 	// Add the parameters to the url.
 	if err := expandURL(req.URL, params); err != nil {
 		return nil, fmt.Errorf("expanding URL with parameters failed: %v", err)