Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

embed/caps.go

go
// The installation's own data caps (EMBED_CONTRACT.md, "Backend: per-user
// data caps" and "The cap object"). The backend sets them with the root
// credential; the app only reads its own, with its client JWT, from GET
// /network/client-data-cap. Usage is accounted when transfer contracts
// settle, so the used counts lag live traffic.
package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
)

const (
	cappedReasonMonthly = "monthly"
	cappedReasonTotal   = "total"
)

// The server refuses the cap read with this message while the team has not
// enabled Embed for the network (EMBED_CONTRACT.md, "Embed enablement"). It
// clears the last reading, so both data fields read unavailable.
var errEmbedNotEnabled = errors.New("Embed isn't enabled for this network.")

// One cap reading: the fields of the cap object that the status uses.
type capReading struct {
	// nil for no cap
	monthlyByteLimit     *int64
	monthlyUsedByteCount int64
	// RFC 3339; when monthly usage resets
	monthlyPeriodEnd string
	// nil for no cap
	totalByteLimit     *int64
	totalUsedByteCount int64
	capped             bool
	// "monthly", "total", or "" when not capped; another value reads as
	// capped without a reset time
	cappedReason string
}

// Whether the cap that capped_reason names is 0: the backend paused this
// installation.
func (self *capReading) paused() bool {
	switch self.cappedReason {
	case cappedReasonMonthly:
		return self.monthlyByteLimit != nil && *self.monthlyByteLimit == 0
	case cappedReasonTotal:
		return self.totalByteLimit != nil && *self.totalByteLimit == 0
	default:
		return false
	}
}

// Parses a cap object. A null or absent limit is no cap; an error object is
// a failed reading. expectedClientId must be its client.
func parseCapObject(raw []byte, expectedClientId string) (*capReading, error) {
	var parsed struct {
		ClientId             string `json:"client_id"`
		MonthlyByteLimit     *int64 `json:"monthly_byte_limit"`
		MonthlyUsedByteCount int64  `json:"monthly_used_byte_count"`
		MonthlyPeriodEnd     string `json:"monthly_period_end"`
		TotalByteLimit       *int64 `json:"total_byte_limit"`
		TotalUsedByteCount   int64  `json:"total_used_byte_count"`
		Capped               bool   `json:"capped"`
		CappedReason         string `json:"capped_reason"`
		Error                *struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.Unmarshal(raw, &parsed); err != nil {
		return nil, errors.New("invalid cap object")
	}
	if parsed.Error != nil {
		if parsed.Error.Message == errEmbedNotEnabled.Error() {
			return nil, errEmbedNotEnabled
		}
		return nil, fmt.Errorf("the cap read failed: %s", oneLine(parsed.Error.Message))
	}
	if parsed.ClientId != expectedClientId {
		return nil, errors.New("the cap object is for another client")
	}
	return &capReading{
		monthlyByteLimit:     parsed.MonthlyByteLimit,
		monthlyUsedByteCount: parsed.MonthlyUsedByteCount,
		monthlyPeriodEnd:     parsed.MonthlyPeriodEnd,
		totalByteLimit:       parsed.TotalByteLimit,
		totalUsedByteCount:   parsed.TotalUsedByteCount,
		capped:               parsed.Capped,
		cappedReason:         parsed.CappedReason,
	}, nil
}

// Reads this installation's caps with its client JWT. A server without the
// cap routes answers 404, which is a failed reading.
func readOwnDataCap(ctx context.Context, client *http.Client, apiOrigin string, clientJwt string, clientId string) (*capReading, error) {
	request, err := http.NewRequestWithContext(ctx, http.MethodGet, apiOrigin+"/network/client-data-cap", nil)
	if err != nil {
		return nil, err
	}
	request.Header.Set("Authorization", "Bearer "+clientJwt)
	response, err := client.Do(request)
	if err != nil {
		return nil, err
	}
	defer response.Body.Close()
	body, err := io.ReadAll(io.LimitReader(response.Body, responseByteLimit+1))
	if err != nil || responseByteLimit < len(body) {
		return nil, errors.New("the cap answer could not be read")
	}
	if response.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("the cap read answered http %d", response.StatusCode)
	}
	return parseCapObject(body, clientId)
}

// The latest cap reading, as the data fields show it: checking until the
// first reading finishes, unavailable if it failed, and the last successful
// reading after that, which a later failure keeps. The Embed-not-enabled
// refusal is not a passing failure: it clears the last reading.
type capState struct {
	// the latest successful reading; nil before the first success
	reading *capReading
	// true once a reading finished, successfully or not
	attempted bool
}

// Records one reading.
func (self *capState) Record(reading *capReading, err error) {
	self.attempted = true
	if errors.Is(err, errEmbedNotEnabled) {
		self.reading = nil
		return
	}
	if err == nil && reading != nil {
		self.reading = reading
	}
}