Adds a hidden `coder exp api` command that covers **Phase 1 only** of the "Simplified API Access via CLI" RFC, using httpie-style request items as RFC reviewers asked. It's a smaller alternative to #31406, which also ships Phase 3 (`--jq`, `--paginate`, `--verbose`). ``` coder exp api [METHOD] <path> [REQUEST_ITEM ...] ``` | Item | Meaning | |---|---| | `Name:value` | Request header | | `Name:` | Remove a request header, such as the default `Content-Type` | | `name==value` | Query parameter, appended to any query already in the path | | `name=value` | JSON string field | | `name:=json` | Raw JSON field (number, bool, null, array, object) | | `name=@file` / `name:=@file` | String or JSON field read from a file, `-` for stdin | - The path is relative to `/api/v2/`. A path that starts with `api/` or `/api/` is used as given, for example `/api/experimental/chats`. - METHOD is optional. The first argument counts as a method only when it matches a known HTTP method, so paths like `users` still work. The default is GET, or POST when there are data items or `--input`. - `--input <file|->` sends a raw body. It can't be combined with data items, the combination is rejected before any file or stdin is read, and stdin is never read implicitly. - There's no `-H` flag. Per-request headers are `Name:value` items, and the existing global `--header` / `--header-command` flags still apply because the command uses `r.InitClient`. Their values are sent in addition to header items. - Auth, TLS and the deployment URL all come from the existing CLI session (`CODER_URL`, `CODER_SESSION_TOKEN`, or `coder login` state). There's no new auth logic. - The command refuses absolute URLs and `.` or `..` path segments, including percent-encoded ones, so the token only goes to API routes on the configured deployment. It warns (but doesn't block) when that URL is plain HTTP to a host that isn't loopback. - httpie forms that would mean something different here are rejected rather than sent literally: `==@` and `:@` file separators, nested JSON field names such as `a[b]=c`, and a `Host` item. - It prints the raw response body. On 4xx/5xx it prints the body and exits non-zero with the Coder error, plus an API reference hint when the route doesn't exist. - No new dependencies. `go.mod` and `go.sum` are unchanged. **Left out on purpose:** `--jq`, `--paginate`, `-i/--include`, request/response logging, and gh-style `-X`/`-f`/`-F`/`-H` flags. **Decisions still open in the RFC:** - Whether httpie syntax is final. - Whether `--paginate`/`--jq` belong in Phase 1 at all. The RFC lists them under both the initial requirements and Phase 3. - An explicit `GET` with data items sends a JSON body, which is what httpie does. The new code is `cli/exp_api.go`, plus a one-line registration in `cli/root.go`. Tests are in `cli/exp_api_internal_test.go` (parsing) and `cli/exp_api_test.go` (integration). Tests run in the workspace: - `go test ./cli/ -run 'TestExpAPI|TestAPIURLIsInsecure|TestAPIRequestPath|TestSplitAPI|TestParseAPIRequestItems'`, also with `-race` plus `TestCommandHelp` - `go vet ./cli/` - `golangci-lint run ./cli/...` - `make lint/go/new-code`, and `make lint/go` through the pre-commit hook > [!NOTE] > This PR was generated by Coder Agents on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
411 lines
13 KiB
Go
411 lines
13 KiB
Go
package cli
|
|
|
|
import (
|
|
"bytes"
|
|
"encoding/json"
|
|
"io"
|
|
"net"
|
|
"net/http"
|
|
"net/url"
|
|
"os"
|
|
"strings"
|
|
|
|
"golang.org/x/xerrors"
|
|
|
|
"github.com/coder/coder/v2/cli/cliui"
|
|
"github.com/coder/coder/v2/codersdk"
|
|
"github.com/coder/serpent"
|
|
)
|
|
|
|
// apiMethods are the HTTP methods accepted as the optional first argument of
|
|
// `coder exp api`. Any other first argument is treated as the path.
|
|
var apiMethods = []string{
|
|
http.MethodGet,
|
|
http.MethodHead,
|
|
http.MethodPost,
|
|
http.MethodPut,
|
|
http.MethodPatch,
|
|
http.MethodDelete,
|
|
http.MethodOptions,
|
|
}
|
|
|
|
// apiCmd makes an authenticated request to an arbitrary Coder API path and
|
|
// writes the raw response body to stdout. Request items follow httpie syntax.
|
|
func (r *RootCmd) apiCmd() *serpent.Command {
|
|
var input string
|
|
cmd := &serpent.Command{
|
|
Use: "api [METHOD] <path> [REQUEST_ITEM ...]",
|
|
Short: "Make an authenticated HTTP request to the Coder API and print the response.",
|
|
Long: "The path is relative to /api/v2/, with or without a leading slash. " +
|
|
"Paths that start with api/ or /api/ are used as given, for example /api/experimental/chats. " +
|
|
"Paths cannot contain . or .. segments.\n\n" +
|
|
"METHOD is optional and defaults to GET, or POST when the request has data items or --input.\n\n" +
|
|
"Request items use httpie syntax:\n" +
|
|
" Name:value request header\n" +
|
|
" Name: remove a request header, such as the default Content-Type\n" +
|
|
" name==value query parameter\n" +
|
|
" name=value JSON string field\n" +
|
|
" name:=json raw JSON field: number, bool, null, array, or object\n" +
|
|
" name=@file JSON string field read from a file, or - for stdin\n" +
|
|
" name:=@file raw JSON field read from a file, or - for stdin\n\n" +
|
|
"Data items build a JSON object body. Escape a separator character in a key with a backslash, " +
|
|
"for example foo\\==bar. Escapes also apply to file paths, so on Windows use forward slashes, " +
|
|
"for example name=@C:/data/file.json. Use --input to send a raw body instead of data items.\n\n" +
|
|
"Headers from the global --header and --header-command flags are sent in addition to header items.\n\n" +
|
|
FormatExamples(
|
|
Example{
|
|
Description: "Get the authenticated user",
|
|
Command: "coder exp api users/me",
|
|
},
|
|
Example{
|
|
Description: "List users with a search query",
|
|
Command: "coder exp api users q==status:active limit==10",
|
|
},
|
|
Example{
|
|
Description: "List your unread inbox notifications",
|
|
Command: "coder exp api notifications/inbox read_status==unread",
|
|
},
|
|
Example{
|
|
Description: "Search the audit log for deleted workspaces",
|
|
Command: "coder exp api audit 'q==resource_type:workspace action:delete' limit==25",
|
|
},
|
|
Example{
|
|
Description: "Create a user in an organization, reading the password from stdin",
|
|
Command: `printf '%s' "$PASSWORD" | coder exp api users username=alice email=alice@example.com password=@- 'organization_ids:=["<org-id>"]'`,
|
|
},
|
|
Example{
|
|
Description: "Send a JSON body from stdin",
|
|
Command: `echo '{"name":"new-name"}' | coder exp api PATCH workspaces/<id> --input -`,
|
|
},
|
|
),
|
|
Middleware: serpent.RequireRangeArgs(1, -1),
|
|
Handler: func(inv *serpent.Invocation) error {
|
|
method, rawPath, rawItems := splitAPIArgs(inv.Args)
|
|
if rawPath == "" {
|
|
return xerrors.Errorf("missing path after method %s", method)
|
|
}
|
|
path, err := apiRequestPath(rawPath)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
// Checked before parsing so that no file or stdin is read for a
|
|
// request that is rejected.
|
|
if input != "" && hasAPIDataItems(rawItems) {
|
|
return xerrors.New("--input cannot be combined with data items")
|
|
}
|
|
items, err := parseAPIRequestItems(rawItems, inv.Stdin)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if method == "" {
|
|
method = http.MethodGet
|
|
if input != "" || len(items.data) > 0 {
|
|
method = http.MethodPost
|
|
}
|
|
}
|
|
|
|
var body any
|
|
switch {
|
|
case input == "-":
|
|
body = inv.Stdin
|
|
case input != "":
|
|
f, err := os.Open(input)
|
|
if err != nil {
|
|
return xerrors.Errorf("open input: %w", err)
|
|
}
|
|
defer f.Close()
|
|
body = f
|
|
case len(items.data) > 0:
|
|
body = items.data
|
|
}
|
|
|
|
client, err := r.InitClient(inv)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if apiURLIsInsecure(client.URL) {
|
|
cliui.Warn(inv.Stderr, "The session token is sent over unencrypted HTTP to "+client.URL.Host+".",
|
|
"Use an https:// URL for the deployment to protect the token.")
|
|
}
|
|
|
|
resp, err := client.Request(inv.Context(), method, path, body, func(req *http.Request) {
|
|
// Append to the raw query so a query already in the path is
|
|
// sent exactly as written.
|
|
if encoded := items.query.Encode(); encoded != "" {
|
|
if req.URL.RawQuery != "" {
|
|
req.URL.RawQuery += "&"
|
|
}
|
|
req.URL.RawQuery += encoded
|
|
}
|
|
for k, vs := range items.headers {
|
|
// A Name: item with no value removes the header.
|
|
if len(vs) == 0 {
|
|
req.Header.Del(k)
|
|
continue
|
|
}
|
|
req.Header[k] = vs
|
|
}
|
|
})
|
|
if err != nil {
|
|
return xerrors.Errorf("%s %s: %w", method, path, err)
|
|
}
|
|
defer resp.Body.Close()
|
|
if resp.StatusCode >= http.StatusBadRequest {
|
|
return writeAPIError(inv.Stdout, resp)
|
|
}
|
|
if _, err := io.Copy(inv.Stdout, resp.Body); err != nil {
|
|
return xerrors.Errorf("read response body: %w", err)
|
|
}
|
|
return nil
|
|
},
|
|
}
|
|
cmd.Options = serpent.OptionSet{
|
|
{
|
|
Flag: "input",
|
|
Description: "The file to use as the raw request body, or - to read from stdin. Cannot be combined with data items.",
|
|
Value: serpent.StringOf(&input),
|
|
},
|
|
}
|
|
return cmd
|
|
}
|
|
|
|
// splitAPIArgs separates the optional method, the path, and the request
|
|
// items. The first argument is a method only when it matches a known HTTP
|
|
// method, so paths such as "users" are never mistaken for one. The returned
|
|
// path is empty when only a method was given.
|
|
func splitAPIArgs(args []string) (method, path string, items []string) {
|
|
first := strings.ToUpper(args[0])
|
|
for _, m := range apiMethods {
|
|
if first == m {
|
|
if len(args) < 2 {
|
|
return m, "", nil
|
|
}
|
|
return m, args[1], args[2:]
|
|
}
|
|
}
|
|
return "", args[0], args[1:]
|
|
}
|
|
|
|
// writeAPIError prints the error body unmodified so scripts can inspect it,
|
|
// then returns the Coder error built from the response.
|
|
func writeAPIError(w io.Writer, resp *http.Response) error {
|
|
raw, err := io.ReadAll(resp.Body)
|
|
if err != nil {
|
|
return xerrors.Errorf("read response body: %w", err)
|
|
}
|
|
if _, err := w.Write(raw); err != nil {
|
|
return xerrors.Errorf("write response body: %w", err)
|
|
}
|
|
resp.Body = io.NopCloser(bytes.NewReader(raw))
|
|
apiErr := codersdk.ReadBodyAsError(resp)
|
|
if sdkErr, ok := codersdk.AsError(apiErr); ok && resp.StatusCode == http.StatusNotFound && sdkErr.Message == "Route not found." {
|
|
sdkErr.Helper = "Check the path against the API reference at https://coder.com/docs/reference/api."
|
|
}
|
|
return apiErr
|
|
}
|
|
|
|
// apiRequestPath turns a user-supplied path into a path under /api/ on the
|
|
// configured deployment. Absolute URLs and dot segments are rejected so the
|
|
// session token is only sent to API routes on that deployment, never to
|
|
// another host or to a workspace app proxied by it.
|
|
func apiRequestPath(raw string) (string, error) {
|
|
pathPart, _, _ := strings.Cut(raw, "?")
|
|
if strings.Contains(pathPart, "://") || strings.HasPrefix(pathPart, "//") {
|
|
return "", xerrors.Errorf("path %q must not include a scheme or host; requests are always sent to the configured Coder URL", raw)
|
|
}
|
|
p := strings.TrimPrefix(raw, "/")
|
|
if p != "api" && !strings.HasPrefix(p, "api/") {
|
|
p = "api/v2/" + p
|
|
}
|
|
p = "/" + p
|
|
u, err := url.Parse(p)
|
|
if err != nil {
|
|
return "", xerrors.Errorf("parse path: %w", err)
|
|
}
|
|
// u.Path is decoded, so percent-encoded dot segments are rejected too.
|
|
for _, segment := range strings.Split(u.Path, "/") {
|
|
if segment == "." || segment == ".." {
|
|
return "", xerrors.Errorf("path %q must not contain . or .. segments", raw)
|
|
}
|
|
}
|
|
return p, nil
|
|
}
|
|
|
|
// apiURLIsInsecure reports whether requests to u send the session token in
|
|
// clear text over a network. Loopback addresses are exempt so local
|
|
// development deployments do not warn.
|
|
func apiURLIsInsecure(u *url.URL) bool {
|
|
if u == nil || u.Scheme != "http" {
|
|
return false
|
|
}
|
|
host := u.Hostname()
|
|
if host == "localhost" {
|
|
return false
|
|
}
|
|
ip := net.ParseIP(host)
|
|
return ip == nil || !ip.IsLoopback()
|
|
}
|
|
|
|
// apiItemSeparators lists request item separators from longest to shortest,
|
|
// so the longest separator wins when several match at the same position.
|
|
// ==@ and :@ are matched only to reject them, because httpie reads their
|
|
// values from a file and this command does not support that yet.
|
|
var apiItemSeparators = []string{":=@", "==@", "=@", "==", ":=", ":@", "=", ":"}
|
|
|
|
// apiEscapable holds the characters a backslash escapes in a request item.
|
|
// A backslash before any other character is kept literally, as in httpie.
|
|
const apiEscapable = ":=@"
|
|
|
|
type apiRequestItems struct {
|
|
headers http.Header
|
|
query url.Values
|
|
data map[string]any
|
|
}
|
|
|
|
// parseAPIRequestItems parses httpie-style request items and reads the file
|
|
// or stdin sources that data items refer to.
|
|
func parseAPIRequestItems(raw []string, stdin io.Reader) (apiRequestItems, error) {
|
|
items := apiRequestItems{
|
|
headers: http.Header{},
|
|
query: url.Values{},
|
|
data: map[string]any{},
|
|
}
|
|
readStdin := false
|
|
for _, arg := range raw {
|
|
key, sep, value, ok := splitAPIRequestItem(arg)
|
|
if !ok {
|
|
return items, xerrors.Errorf("invalid request item %q: expected Name:value, name==value, name=value, name:=json, name=@file, or name:=@file", arg)
|
|
}
|
|
if key == "" {
|
|
return items, xerrors.Errorf("invalid request item %q: missing name", arg)
|
|
}
|
|
switch sep {
|
|
case ":":
|
|
key = http.CanonicalHeaderKey(key)
|
|
if key == "Host" {
|
|
return items, xerrors.Errorf("invalid request item %q: the Host header cannot be set; requests are always sent to the configured Coder URL", arg)
|
|
}
|
|
value = strings.TrimSpace(value)
|
|
if value == "" {
|
|
// An empty list removes the header and any earlier values for
|
|
// it, as Name: does in httpie.
|
|
items.headers[key] = []string{}
|
|
continue
|
|
}
|
|
items.headers.Add(key, value)
|
|
continue
|
|
case "==":
|
|
items.query.Add(key, value)
|
|
continue
|
|
case "==@", ":@":
|
|
return items, xerrors.Errorf("invalid request item %q: reading a query parameter or header from a file is not supported; escape the @ with a backslash to send it literally", arg)
|
|
}
|
|
|
|
// httpie reserves [ in field names for nested JSON, so reject it
|
|
// rather than send a literal key that a later version would change.
|
|
if strings.Contains(key, "[") {
|
|
return items, xerrors.Errorf("invalid request item %q: nested JSON field names are not supported; use name:=json to send a nested value", arg)
|
|
}
|
|
if _, exists := items.data[key]; exists {
|
|
return items, xerrors.Errorf("duplicate data field %q", key)
|
|
}
|
|
if sep == "=@" || sep == ":=@" {
|
|
if value == "-" {
|
|
if readStdin {
|
|
return items, xerrors.Errorf("request item %q: only one request item can read stdin", arg)
|
|
}
|
|
readStdin = true
|
|
}
|
|
b, err := readAPIItemFile(value, stdin)
|
|
if err != nil {
|
|
return items, xerrors.Errorf("request item %q: %w", arg, err)
|
|
}
|
|
value = string(b)
|
|
}
|
|
switch sep {
|
|
case "=", "=@":
|
|
items.data[key] = value
|
|
case ":=", ":=@":
|
|
if !json.Valid([]byte(value)) {
|
|
return items, xerrors.Errorf("request item %q: value is not valid JSON", arg)
|
|
}
|
|
items.data[key] = json.RawMessage(value)
|
|
}
|
|
}
|
|
return items, nil
|
|
}
|
|
|
|
// hasAPIDataItems reports whether any request item adds a field to the JSON
|
|
// body. It does not read any file or stdin source.
|
|
func hasAPIDataItems(raw []string) bool {
|
|
for _, arg := range raw {
|
|
_, sep, _, ok := splitAPIRequestItem(arg)
|
|
if !ok {
|
|
continue
|
|
}
|
|
switch sep {
|
|
case "=", ":=", "=@", ":=@":
|
|
return true
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
func readAPIItemFile(name string, stdin io.Reader) ([]byte, error) {
|
|
if name == "-" {
|
|
b, err := io.ReadAll(stdin)
|
|
if err != nil {
|
|
return nil, xerrors.Errorf("read stdin: %w", err)
|
|
}
|
|
return b, nil
|
|
}
|
|
b, err := os.ReadFile(name)
|
|
if err != nil {
|
|
return nil, xerrors.Errorf("read file: %w", err)
|
|
}
|
|
return b, nil
|
|
}
|
|
|
|
// splitAPIRequestItem finds the first unescaped position where a separator
|
|
// matches, takes the longest separator at that position, and returns the
|
|
// unescaped key and value around it.
|
|
func splitAPIRequestItem(arg string) (key, sep, value string, ok bool) {
|
|
type char struct {
|
|
r rune
|
|
escaped bool
|
|
}
|
|
runes := []rune(arg)
|
|
chars := make([]char, 0, len(runes))
|
|
for i := 0; i < len(runes); i++ {
|
|
if runes[i] == '\\' && i+1 < len(runes) && strings.ContainsRune(apiEscapable, runes[i+1]) {
|
|
chars = append(chars, char{r: runes[i+1], escaped: true})
|
|
i++
|
|
continue
|
|
}
|
|
chars = append(chars, char{r: runes[i]})
|
|
}
|
|
join := func(cs []char) string {
|
|
rs := make([]rune, len(cs))
|
|
for i, c := range cs {
|
|
rs[i] = c.r
|
|
}
|
|
return string(rs)
|
|
}
|
|
matches := func(at int, s string) bool {
|
|
for j, r := range []rune(s) {
|
|
if at+j >= len(chars) || chars[at+j].escaped || chars[at+j].r != r {
|
|
return false
|
|
}
|
|
}
|
|
return true
|
|
}
|
|
for i := range chars {
|
|
for _, s := range apiItemSeparators {
|
|
if matches(i, s) {
|
|
return join(chars[:i]), s, join(chars[i+len([]rune(s)):]), true
|
|
}
|
|
}
|
|
}
|
|
return "", "", "", false
|
|
}
|