Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

embed/server/api.go

go
// The URnetwork API calls of the embed backend, made with the root
// credential: provision and reissue clients (POST /network/auth-client), set
// and read data caps (POST and GET /network/client-data-cap, GET
// /network/client-data-caps) and remove clients (POST /network/remove-client).
// The field names follow connect's api/bringyour.yml.
package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strings"
	"time"
)

// the largest response the backend reads
const byteLimit = 1024 * 1024

const httpTimeout = 30 * time.Second

// The server answers a reissue of a deactivated (30 days without connecting)
// or removed client, and a remove of a missing client, with this message.
const clientDoesNotExistMessage = "Client does not exist."

// A server without ACL groups answers their route with 404 (EMBED_CONTRACT.md,
// "ACL groups"). The commands exit 1 with this text; the token server reports
// it and still answers the token.
var errAclUnsupported = errors.New("/network/client-acl-group answered 404: the server predates ACL groups")

// The server answers the data-cap and ACL-group routes with this refusal while
// the team has not enabled Embed for the caller's network (EMBED_CONTRACT.md,
// "Embed enablement"). Caps and groups set earlier stay enforced.
const embedNotEnabledMessage = "Embed isn't enabled for this network."

// Whether err is the server's Embed-not-enabled refusal.
func isEmbedNotEnabled(err error) bool {
	var refusal *apiRefusal
	return errors.As(err, &refusal) && refusal.message == embedNotEnabledMessage
}

// Sends one api request: the method, the path (with its query) below the api
// origin and an optional json body. Returns the http status and the bounded
// response body.
type apiTransport func(method string, path string, body []byte) (int, []byte, error)

// A call that the server answered with its error object.
type apiRefusal struct {
	message string
	// error.client_limit_exceeded or error.upgrade_required: the network is
	// at its client limit or its plan's concurrent client limit
	clientLimit bool
}

// The server's message on one line.
func (self *apiRefusal) Error() string {
	return fmt.Sprintf("the URnetwork API refused the request: %s", oneLine(self.message))
}

// Whether err is the server's "Client does not exist." refusal.
func isClientDoesNotExist(err error) bool {
	var refusal *apiRefusal
	return errors.As(err, &refusal) && refusal.message == clientDoesNotExistMessage
}

// Whether err is a client limit refusal, for either flag.
func isClientLimit(err error) bool {
	var refusal *apiRefusal
	return errors.As(err, &refusal) && refusal.clientLimit
}

// The URnetwork API failed: it could not be reached, answered an unexpected
// status or something invalid, or refused the root credential. The token
// server answers these with 502; a refused root credential also unwraps to
// a configError, so the commands exit 78 for it.
type upstreamError struct {
	err error
}

// The cause on one line.
func (self *upstreamError) Error() string {
	return self.err.Error()
}

// The cause.
func (self *upstreamError) Unwrap() error {
	return self.err
}

// An upstream error with a formatted message.
func upstreamErrorf(format string, args ...any) error {
	return &upstreamError{err: fmt.Errorf(format, args...)}
}

// The api calls, over one transport.
type apiClient struct {
	transport apiTransport
}

// Sends one request and returns the 2xx response body. A 401 or 403 means the
// server refused the root credential: a configuration error.
func (self *apiClient) call(method string, path string, body []byte) ([]byte, error) {
	status, response, err := self.transport(method, path, body)
	if err != nil {
		return nil, upstreamErrorf("the URnetwork API could not be reached: %v", err)
	}
	if status == http.StatusUnauthorized || status == http.StatusForbidden {
		return nil, &upstreamError{err: configErrorf("the URnetwork API refused the root credential (http %d)", status)}
	}
	if status == http.StatusNotFound && strings.HasPrefix(path, "/network/client-acl-group") {
		return nil, &upstreamError{err: errAclUnsupported}
	}
	if status == http.StatusNotFound && strings.HasPrefix(path, "/network/client-data-cap") {
		// a server without the data-cap routes (EMBED_CONTRACT.md, "Backend tools")
		route, _, _ := strings.Cut(path, "?")
		return nil, upstreamErrorf("%s answered 404: the server predates the data-cap routes", route)
	}
	if status == http.StatusNotFound && path == "/network/embed" {
		// a server without Embed enablement (EMBED_CONTRACT.md, "Backend tools")
		return nil, upstreamErrorf("/network/embed answered 404: the server predates Embed enablement")
	}
	if status < 200 || 300 <= status {
		return nil, upstreamErrorf("the URnetwork API answered http %d", status)
	}
	return response, nil
}

// One POST /network/auth-client request for a top-level client. ClientId is
// set only to reissue; source_client_id is never sent.
type authClientArgs struct {
	ClientId    string `json:"client_id,omitempty"`
	Description string `json:"description"`
	DeviceSpec  string `json:"device_spec"`
}

// Provisions a new client (args.ClientId empty) or reissues args.ClientId,
// and returns the client id and its scoped client JWT. A refusal answers 200
// with the error object. The JWT's client_id claim must name the answered
// client, a reissue must answer the stored client, and the claim is read
// without verifying the token, which the server signs and the SDK verifies.
func (self *apiClient) AuthClient(args *authClientArgs) (string, string, error) {
	request, err := json.Marshal(args)
	if err != nil {
		return "", "", err
	}
	body, err := self.call(http.MethodPost, "/network/auth-client", request)
	if err != nil {
		return "", "", err
	}
	var result struct {
		ClientId    string `json:"client_id"`
		ByClientJwt string `json:"by_client_jwt"`
		Error       *struct {
			ClientLimitExceeded bool   `json:"client_limit_exceeded"`
			UpgradeRequired     bool   `json:"upgrade_required"`
			Message             string `json:"message"`
		} `json:"error"`
	}
	if err := json.Unmarshal(body, &result); err != nil {
		return "", "", upstreamErrorf("the URnetwork API answered auth-client with something invalid")
	}
	if result.Error != nil {
		return "", "", &apiRefusal{
			message:     result.Error.Message,
			clientLimit: result.Error.ClientLimitExceeded || result.Error.UpgradeRequired,
		}
	}
	if !uuidPattern.MatchString(result.ClientId) {
		return "", "", upstreamErrorf("the URnetwork API answered auth-client with no valid client_id")
	}
	if args.ClientId != "" && result.ClientId != args.ClientId {
		return "", "", upstreamErrorf("the URnetwork API reissued another client")
	}
	var claims struct {
		ClientId string `json:"client_id"`
	}
	if err := decodeJwtClaims(result.ByClientJwt, &claims); err != nil || claims.ClientId != result.ClientId {
		return "", "", upstreamErrorf("the client JWT does not name the answered client")
	}
	return result.ClientId, result.ByClientJwt, nil
}

// Posts a POST /network/client-data-cap body and returns the client's cap
// object after the change.
func (self *apiClient) SetDataCap(clientId string, request []byte) (json.RawMessage, error) {
	body, err := self.call(http.MethodPost, "/network/client-data-cap", request)
	if err != nil {
		return nil, err
	}
	return parseCapObject(body, clientId)
}

// Reads one client's cap object.
func (self *apiClient) GetDataCap(clientId string) (json.RawMessage, error) {
	body, err := self.call(http.MethodGet, "/network/client-data-cap?client_id="+url.QueryEscape(clientId), nil)
	if err != nil {
		return nil, err
	}
	return parseCapObject(body, clientId)
}

// Reads one page of GET /network/client-data-caps with limit=1000: the cap
// objects of the network's capped clients and the next cursor, nil on the
// last page.
func (self *apiClient) ListDataCaps(cursor string) ([]json.RawMessage, *string, error) {
	path := "/network/client-data-caps?limit=1000"
	if cursor != "" {
		path += "&cursor=" + url.QueryEscape(cursor)
	}
	body, err := self.call(http.MethodGet, path, nil)
	if err != nil {
		return nil, nil, err
	}
	var result struct {
		Clients    []json.RawMessage `json:"clients"`
		NextCursor *string           `json:"next_cursor"`
		Error      *struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.Unmarshal(body, &result); err != nil {
		return nil, nil, upstreamErrorf("the URnetwork API answered client-data-caps with something invalid")
	}
	if result.Error != nil {
		return nil, nil, &apiRefusal{message: result.Error.Message}
	}
	capObjects := make([]json.RawMessage, 0, len(result.Clients))
	for _, raw := range result.Clients {
		capObject, err := parseCapObject(raw, "")
		if err != nil {
			return nil, nil, err
		}
		capObjects = append(capObjects, capObject)
	}
	return capObjects, result.NextCursor, nil
}

// Sets one client's ACL group with POST /network/client-acl-group and
// returns the answer, {"client_id": "...", "acl_group": "..."}, after
// checking that it names the client and the group.
func (self *apiClient) SetAclGroup(clientId string, aclGroup string) (json.RawMessage, error) {
	request, err := json.Marshal(map[string]string{"client_id": clientId, "acl_group": aclGroup})
	if err != nil {
		return nil, err
	}
	body, err := self.call(http.MethodPost, "/network/client-acl-group", request)
	if err != nil {
		return nil, err
	}
	var result struct {
		ClientId string `json:"client_id"`
		AclGroup string `json:"acl_group"`
		Error    *struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.Unmarshal(body, &result); err != nil {
		return nil, upstreamErrorf("the URnetwork API answered client-acl-group with something invalid")
	}
	if result.Error != nil {
		return nil, &apiRefusal{message: result.Error.Message}
	}
	if result.ClientId != clientId || result.AclGroup != aclGroup {
		return nil, upstreamErrorf("the URnetwork API answered client-acl-group for another client or group")
	}
	return json.Marshal(map[string]string{"client_id": result.ClientId, "acl_group": result.AclGroup})
}

// The network's Embed state (EMBED_CONTRACT.md, "Embed enablement").
type embedState struct {
	enabled           bool
	clientLimit       int64
	activeClientCount int64
}

// Reads GET /network/embed, which takes the network credential only: a
// refusal, such as for a client JWT, answers 200 with the error object.
func (self *apiClient) GetEmbed() (*embedState, error) {
	body, err := self.call(http.MethodGet, "/network/embed", nil)
	if err != nil {
		return nil, err
	}
	var result struct {
		Enabled           *bool  `json:"enabled"`
		ClientLimit       *int64 `json:"client_limit"`
		ActiveClientCount *int64 `json:"active_client_count"`
		Error             *struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.Unmarshal(body, &result); err != nil {
		return nil, upstreamErrorf("the URnetwork API answered network/embed with something invalid")
	}
	if result.Error != nil {
		return nil, &apiRefusal{message: result.Error.Message}
	}
	if result.Enabled == nil || result.ClientLimit == nil || result.ActiveClientCount == nil || *result.ClientLimit < 0 || *result.ActiveClientCount < 0 {
		return nil, upstreamErrorf("the URnetwork API answered network/embed with something invalid")
	}
	return &embedState{
		enabled:           *result.Enabled,
		clientLimit:       *result.ClientLimit,
		activeClientCount: *result.ActiveClientCount,
	}, nil
}

// Removes one client. A missing client answers the "Client does not exist."
// refusal.
func (self *apiClient) RemoveClient(clientId string) error {
	request, err := json.Marshal(map[string]string{"client_id": clientId})
	if err != nil {
		return err
	}
	body, err := self.call(http.MethodPost, "/network/remove-client", request)
	if err != nil {
		return err
	}
	var result struct {
		Error *struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.Unmarshal(body, &result); err != nil {
		return upstreamErrorf("the URnetwork API answered remove-client with something invalid")
	}
	if result.Error != nil {
		return &apiRefusal{message: result.Error.Message}
	}
	return nil
}

// The fields of a cap object (EMBED_CONTRACT.md, "The cap object") that the
// backend checks before it prints or returns the object.
type capObject struct {
	ClientId             string `json:"client_id"`
	MonthlyByteLimit     *int64 `json:"monthly_byte_limit"`
	MonthlyUsedByteCount int64  `json:"monthly_used_byte_count"`
	MonthlyPeriodStart   string `json:"monthly_period_start"`
	MonthlyPeriodEnd     string `json:"monthly_period_end"`
	TotalByteLimit       *int64 `json:"total_byte_limit"`
	TotalUsedByteCount   int64  `json:"total_used_byte_count"`
	TotalPeriodStart     string `json:"total_period_start"`
	Capped               bool   `json:"capped"`
	CappedReason         string `json:"capped_reason"`
	Error                *struct {
		Message string `json:"message"`
	} `json:"error"`
}

// Checks one cap object and returns it compacted, with every field the
// server sent. expectedClientId, when set, must be its client.
func parseCapObject(raw []byte, expectedClientId string) (json.RawMessage, error) {
	var parsed capObject
	if err := json.Unmarshal(raw, &parsed); err != nil {
		return nil, upstreamErrorf("the URnetwork API answered an invalid cap object")
	}
	if parsed.Error != nil {
		return nil, &apiRefusal{message: parsed.Error.Message}
	}
	if !uuidPattern.MatchString(parsed.ClientId) || (expectedClientId != "" && parsed.ClientId != expectedClientId) {
		return nil, upstreamErrorf("the URnetwork API answered a cap object for another client")
	}
	compact := &bytes.Buffer{}
	if err := json.Compact(compact, raw); err != nil {
		return nil, err
	}
	return json.RawMessage(compact.Bytes()), nil
}

// Decodes the claims of a JWT into claims, without verifying the token.
func decodeJwtClaims(jwt string, claims any) error {
	parts := strings.Split(jwt, ".")
	if len(parts) != 3 || parts[0] == "" || parts[1] == "" || parts[2] == "" {
		return errors.New("not a JWT")
	}
	payload, err := base64.RawURLEncoding.DecodeString(strings.TrimRight(parts[1], "="))
	if err != nil {
		return errors.New("not a JWT")
	}
	if err := json.Unmarshal(payload, claims); err != nil {
		return errors.New("not a JWT")
	}
	return nil
}

// An api transport over https with the root credential. Redirects are not
// followed, so the credential only goes to the configured origin.
func newHttpTransport(origin string, rootCredential string) apiTransport {
	client := &http.Client{
		Timeout: httpTimeout,
		CheckRedirect: func(*http.Request, []*http.Request) error {
			return http.ErrUseLastResponse
		},
	}
	return func(method string, path string, body []byte) (int, []byte, error) {
		var requestBody io.Reader
		if body != nil {
			requestBody = bytes.NewReader(body)
		}
		request, err := http.NewRequest(method, origin+path, requestBody)
		if err != nil {
			return 0, nil, err
		}
		request.Header.Set("Authorization", "Bearer "+rootCredential)
		if body != nil {
			request.Header.Set("Content-Type", "application/json")
		}
		response, err := client.Do(request)
		if err != nil {
			return 0, nil, err
		}
		defer response.Body.Close()
		responseBody, err := io.ReadAll(io.LimitReader(response.Body, byteLimit+1))
		if err != nil {
			return 0, nil, err
		}
		if byteLimit < len(responseBody) {
			return 0, nil, errors.New("response too large")
		}
		return response.StatusCode, responseBody, nil
	}
}

// An https origin without credentials, path, query or fragment. Plain http is
// accepted only for an explicit loopback mock.
func apiOrigin(apiUrl string) (string, error) {
	parsed, err := url.Parse(apiUrl)
	if err != nil {
		return "", configErrorf("URNETWORK_API_URL is not a URL")
	}
	hostName := parsed.Hostname()
	loopback := hostName == "localhost" || hostName == "127.0.0.1" || hostName == "::1"
	if hostName == "" || parsed.User != nil || (parsed.Path != "" && parsed.Path != "/") || parsed.RawQuery != "" || parsed.Fragment != "" || (parsed.Scheme != "https" && !(parsed.Scheme == "http" && loopback)) {
		return "", configErrorf("URNETWORK_API_URL must be an https origin, or explicit loopback http for a mock")
	}
	return strings.TrimSuffix(apiUrl, "/"), nil
}