Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

embed/server/commands.go

go
// The backend commands (EMBED_CONTRACT.md, "Backend tools"): provision a
// key's client, set and read its data caps, read every capped client, and
// remove a client. They use the token server's map and settings, so they
// manage the clients the token server provisions.
package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"path/filepath"
)

// The settings, api and map of one command.
type backendTool struct {
	api    *apiClient
	store  *mapStore
	issuer *issuer
	out    io.Writer
	errOut io.Writer
}

// Validates the shared settings.
func newBackendTool(env *environment) (*backendTool, error) {
	shared, err := loadSettings(env.getenv)
	if err != nil {
		return nil, err
	}
	api := &apiClient{transport: env.transport(shared.apiOrigin, shared.rootCredential)}
	store := newMapStore(shared.mapPath)
	return &backendTool{
		api:   api,
		store: store,
		issuer: &issuer{
			api:         api,
			store:       store,
			defaults:    shared.defaults,
			aclGroup:    shared.defaultAclGroup,
			description: commandDescription,
			deviceSpec:  commandDeviceSpec,
		},
		out:    env.stdout,
		errOut: env.stderr,
	}, nil
}

// Reissues the key's client, or provisions a new one (also when the server no
// longer has the mapped client), applies any default caps it still owes, and
// writes its client JWT to clientJwtPath, owner-only and atomically. Prints
// {"client_id": "..."}; the JWT is never printed.
func (self *backendTool) Provision(key string, clientJwtPath string) error {
	if !keyPattern.MatchString(key) {
		return configErrorf("expected a key such as user:alice or user:alice:22222222-2222-2222-2222-222222222222")
	}
	if clientJwtPath == "" {
		return configErrorf("expected the client JWT file to write")
	}
	unlock, err := self.store.Lock()
	if err != nil {
		return err
	}
	defer unlock()
	clients, err := self.store.Load()
	if err != nil {
		return err
	}
	issued, err := self.issuer.Issue(clients, key, nil)
	if err != nil {
		return commandError(err)
	}
	if issued.aclUnsupported {
		// fail closed: no token for a client that is not in its ACL group;
		// pending_acl keeps the key for the next provision
		return &upstreamError{err: errAclUnsupported}
	}
	// the mapping is saved before the token is written, so a failed write is
	// repaired by provisioning again (a reissue)
	if err := writePrivateFile(filepath.Clean(clientJwtPath), []byte(issued.clientJwt+"\n")); err != nil {
		return fmt.Errorf("could not write the client JWT file (provision again to reissue): %v", err)
	}
	if err := printJson(self.out, map[string]string{"client_id": issued.clientId}); err != nil {
		return err
	}
	if issued.embedNotEnabled {
		// the client works; its defaults stay pending until the team enables
		// Embed for the network, and a later provision applies them
		fmt.Fprintln(self.errOut, embedPendingLine)
	}
	return nil
}

// Prints the network's Embed state from GET /network/embed as one line,
// "embed enabled: yes | client limit: 5000 | active clients: 1234". A
// refusal, such as for a client JWT, is a configuration error.
func (self *backendTool) Status() error {
	state, err := self.api.GetEmbed()
	if err != nil {
		var refusal *apiRefusal
		if errors.As(err, &refusal) {
			return &configError{message: refusal.Error()}
		}
		return err
	}
	_, err = fmt.Fprintln(self.out, embedStatusLine(state))
	return err
}

// The status command's line (EMBED_CONTRACT.md, "Backend tools").
func embedStatusLine(state *embedState) string {
	enabled := "no"
	if state.enabled {
		enabled = "yes"
	}
	return fmt.Sprintf("embed enabled: %s | client limit: %d | active clients: %d", enabled, state.clientLimit, state.activeClientCount)
}

// Posts only the given cap options for the key's client and prints its cap
// object.
func (self *backendTool) Cap(key string, args []string) error {
	clientId, err := self.mappedClientId(key)
	if err != nil {
		return err
	}
	options, err := parseCapOptions(args)
	if err != nil {
		return err
	}
	body, err := options.body(clientId)
	if err != nil {
		return err
	}
	capObject, err := self.api.SetDataCap(clientId, body)
	if err != nil {
		return commandError(err)
	}
	return printLine(self.out, capObject)
}

// Prints the key's cap object, read with the root credential.
func (self *backendTool) Usage(key string) error {
	clientId, err := self.mappedClientId(key)
	if err != nil {
		return err
	}
	capObject, err := self.api.GetDataCap(clientId)
	if err != nil {
		return commandError(err)
	}
	return printLine(self.out, capObject)
}

// Sets the ACL group of the key's client, "default" or "isolated", and
// prints the answer, {"client_id": "...", "acl_group": "..."}.
func (self *backendTool) Acl(key string, aclGroup string) error {
	if aclGroup != aclGroupDefault && aclGroup != aclGroupIsolated {
		return configErrorf("%s", usage)
	}
	clientId, err := self.mappedClientId(key)
	if err != nil {
		return err
	}
	answer, err := self.api.SetAclGroup(clientId, aclGroup)
	if err != nil {
		return commandError(err)
	}
	return printLine(self.out, answer)
}

// Pages through GET /network/client-data-caps and prints one cap object per
// line, stopping at a null cursor or one it has already seen.
func (self *backendTool) UsageAll() error {
	seenCursors := map[string]bool{}
	cursor := ""
	for {
		capObjects, nextCursor, err := self.api.ListDataCaps(cursor)
		if err != nil {
			return commandError(err)
		}
		for _, capObject := range capObjects {
			if err := printLine(self.out, capObject); err != nil {
				return err
			}
		}
		if nextCursor == nil || *nextCursor == "" || seenCursors[*nextCursor] {
			return nil
		}
		seenCursors[*nextCursor] = true
		cursor = *nextCursor
	}
}

// Removes the key's client, then its mapping, also when the server answers
// that the client does not exist. Prints {"removed": "<client_id>"}.
func (self *backendTool) Remove(key string) error {
	if !keyPattern.MatchString(key) {
		return configErrorf("expected a key such as user:alice or user:alice:22222222-2222-2222-2222-222222222222")
	}
	unlock, err := self.store.Lock()
	if err != nil {
		return err
	}
	defer unlock()
	clients, err := self.store.Load()
	if err != nil {
		return err
	}
	clientId, ok := clients.Clients[key]
	if !ok {
		return configErrorf("%s", unmappedKeyMessage)
	}
	if err := self.api.RemoveClient(clientId); err != nil && !isClientDoesNotExist(err) {
		return commandError(err)
	}
	clients.Remove(key)
	if err := self.store.Save(clients); err != nil {
		return err
	}
	return printJson(self.out, map[string]string{"removed": clientId})
}

// The fixed text for a key with no mapped client (EMBED_CONTRACT.md, "Backend
// tools"); exit 78.
const unmappedKeyMessage = "no client is mapped for that key; run provision first"

// The client id that the map holds for key.
func (self *backendTool) mappedClientId(key string) (string, error) {
	if !keyPattern.MatchString(key) {
		return "", configErrorf("expected a key such as user:alice or user:alice:22222222-2222-2222-2222-222222222222")
	}
	clients, err := self.store.Load()
	if err != nil {
		return "", err
	}
	clientId, ok := clients.Clients[key]
	if !ok {
		return "", configErrorf("%s", unmappedKeyMessage)
	}
	return clientId, nil
}

// A client limit refusal (either flag) and the Embed-not-enabled refusal are
// configuration errors with the tools' fixed messages.
func commandError(err error) error {
	if isClientLimit(err) {
		return &configError{message: clientLimitMessage}
	}
	if isEmbedNotEnabled(err) {
		return &configError{message: embedNotEnabledLine}
	}
	return err
}

// The cap options of one cap command.
type capOptions struct {
	monthly    optionalLimit
	total      optionalLimit
	resetTotal bool
}

// One limit option: unset (absent from the request), null (clears the cap),
// or a byte count.
type optionalLimit struct {
	set   bool
	null  bool
	value int64
}

// Parses [--monthly <bytes>|null] [--total <bytes>|null] [--reset-total]:
// at least one option, each at most once.
func parseCapOptions(args []string) (*capOptions, error) {
	options := &capOptions{}
	if len(args) == 0 {
		return nil, configErrorf("cap needs at least one of --monthly, --total and --reset-total")
	}
	for i := 0; i < len(args); i += 1 {
		switch args[i] {
		case "--monthly", "--total":
			limit := &options.monthly
			if args[i] == "--total" {
				limit = &options.total
			}
			if limit.set || len(args) <= i+1 {
				return nil, configErrorf("%s takes one value: a byte count or null, at most once", args[i])
			}
			i += 1
			parsed, err := parseLimitValue(args[i])
			if err != nil {
				return nil, err
			}
			*limit = parsed
		case "--reset-total":
			if options.resetTotal {
				return nil, configErrorf("--reset-total is given more than once")
			}
			options.resetTotal = true
		default:
			return nil, configErrorf("unknown cap option %q", args[i])
		}
	}
	return options, nil
}

// A limit option's value: null, or a byte count from 0 to 9223372036854775807
// without units.
func parseLimitValue(text string) (optionalLimit, error) {
	if text == "null" {
		return optionalLimit{set: true, null: true}, nil
	}
	byteCount, err := parseByteCount(text)
	if err != nil {
		return optionalLimit{}, configErrorf("a cap is null or a byte count: a decimal integer from 0 to 9223372036854775807, with no units")
	}
	return optionalLimit{set: true, value: byteCount}, nil
}

// The POST /network/client-data-cap body. Each limit merges on the server:
// an unset option is absent, null is JSON null, a byte count is a JSON
// integer, and reset_total appears only when given.
func (self *capOptions) body(clientId string) ([]byte, error) {
	if !uuidPattern.MatchString(clientId) {
		return nil, errors.New("invalid client id")
	}
	body := map[string]any{"client_id": clientId}
	for _, limit := range []struct {
		name   string
		option optionalLimit
	}{
		{name: "monthly_byte_limit", option: self.monthly},
		{name: "total_byte_limit", option: self.total},
	} {
		switch {
		case !limit.option.set:
		case limit.option.null:
			body[limit.name] = nil
		default:
			body[limit.name] = limit.option.value
		}
	}
	if self.resetTotal {
		body["reset_total"] = true
	}
	return json.Marshal(body)
}

// Prints value as one line of JSON.
func printJson(out io.Writer, value any) error {
	data, err := json.Marshal(value)
	if err != nil {
		return err
	}
	return printLine(out, data)
}

// Prints JSON bytes as one line.
func printLine(out io.Writer, data []byte) error {
	_, err := fmt.Fprintf(out, "%s\n", data)
	return err
}