Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

embed/session.go

go
// A running embedded Device (EMBED_CONTRACT.md, "App lifecycle"): the network
// space manager, the local Device with the installation's client JWT, the
// listeners that keep the credential and refresh the caps, and the status
// loop. SDK listeners run on SDK goroutines, so the fields they write are
// guarded by the session's stateLock.
package main

import (
	"context"
	"fmt"
	"net/http"
	"os"
	"sync"
	"time"

	sdk "github.com/urnetwork/sdk/v2026"
)

// How often the status is read, and the longest gap between status lines.
const statusPollInterval = 1 * time.Second
const statusRepeatInterval = 60 * time.Second

// How often the caps are read again. A contract status change also reads
// them, within 5 seconds.
const capReadInterval = 5 * time.Minute

// The device description and spec recorded for this installation's device.
const deviceDescription = "Go embed example"
const deviceSpec = "urnetwork-examples/go-embed"
const appVersion = "1"

// One run of the embedded Device. Created by newEmbedSession, which starts
// the Device; Run shows the status; Close stops it.
type embedSession struct {
	config     *embedConfig
	clientId   string
	manager    *sdk.NetworkSpaceManager
	device     *sdk.DeviceLocal
	subs       []sdk.Sub
	httpClient *http.Client

	// closed when the server rejects the client credential
	logout     chan struct{}
	logoutOnce sync.Once
	// a contract status change asks for a cap read
	capRefresh chan struct{}

	stateLock sync.Mutex
	// the latest client JWT; the SDK refreshes it
	clientJwt string
	caps      capState
}

// Creates the local Device with the client JWT, adds the listeners and sets
// the connect location to best available, the destination of the app's own
// traffic. An embed app does not provide: the provide mode stays at its
// default.
func newEmbedSession(config *embedConfig, credential *clientCredential) (*embedSession, error) {
	instanceId, err := sdk.ParseId(config.instanceId)
	if err != nil {
		return nil, err
	}
	manager := sdk.NewNetworkSpaceManagerNoStorage()
	space := manager.UpdateNetworkSpaceValues(
		sdk.NewNetworkSpaceKey("ur.network", "main"),
		&sdk.NetworkSpaceValues{MigrationHostName: "bringyour.com"},
	)
	space.GetApi().SetByJwt(credential.clientJwt)
	device, err := sdk.NewDeviceLocalWithDefaults(
		space,
		credential.clientJwt,
		deviceDescription,
		deviceSpec,
		appVersion,
		instanceId,
		false,
	)
	if err != nil {
		manager.Close()
		return nil, err
	}
	session := &embedSession{
		config:     config,
		clientId:   credential.clientId,
		manager:    manager,
		device:     device,
		httpClient: newHttpClient(),
		logout:     make(chan struct{}),
		capRefresh: make(chan struct{}, 1),
		clientJwt:  credential.clientJwt,
	}
	if credential.firstCapReading != nil {
		// the token server's data_cap serves as the first reading
		session.caps.Record(credential.firstCapReading, nil)
	}
	session.subs = []sdk.Sub{
		device.AddJwtRefreshListener(&jwtRefreshListener{session: session}),
		device.AddAuthLogoutListener(&authLogoutListener{session: session}),
		device.AddContractStatusChangeListener(&contractStatusListener{session: session}),
	}
	device.SetConnectLocation(&sdk.ConnectLocation{
		ConnectLocationId: &sdk.ConnectLocationId{BestAvailable: true},
	})
	return session, nil
}

// Reads the status from the device getters and the cap state.
func (self *embedSession) Status() *embedStatus {
	status := &embedStatus{started: true}
	// "client_limit_exceeded" with the hold's end in RetryTime while the
	// platform holds this client off for its network's concurrent client limit
	if clientLimitStatus := self.device.GetClientLimitStatus(); clientLimitStatus != nil {
		status.clientLimitStatus = clientLimitStatus.Status
		status.clientLimitRetryTime = clientLimitStatus.RetryTime
	}
	// nil before the window exists
	if windowStatus := self.device.GetWindowStatus(); windowStatus != nil {
		status.providersAdded = windowStatus.ProviderStateAdded
	}
	self.stateLock.Lock()
	defer self.stateLock.Unlock()
	status.caps = self.caps
	return status
}

// Prints the status until the context ends or the server rejects the
// credential, and returns the process exit code. A line prints when any
// field's text changes, and otherwise once a minute.
func (self *embedSession) Run(ctx context.Context) int {
	readerCtx, stopReader := context.WithCancel(ctx)
	defer stopReader()
	go self.readCaps(readerCtx)
	lastLine := ""
	var lastPrintTime time.Time
	for {
		line := self.Status().String()
		now := time.Now()
		if line != lastLine || statusRepeatInterval <= now.Sub(lastPrintTime) {
			fmt.Println(line)
			lastLine = line
			lastPrintTime = now
		}
		select {
		case <-ctx.Done():
			return exitStopped
		case <-self.logout:
			fmt.Fprintln(os.Stderr, "the server rejected the client credential; sign in again to get a new client JWT from your backend")
			return exitConfig
		case <-time.After(statusPollInterval):
		}
	}
}

// Reads the caps at start (unless the token server's data_cap is the first
// reading), every 5 minutes and after a contract status change.
func (self *embedSession) readCaps(ctx context.Context) {
	haveFirstReading := func() bool {
		self.stateLock.Lock()
		defer self.stateLock.Unlock()
		return self.caps.attempted
	}()
	if !haveFirstReading {
		self.readCapsOnce(ctx)
	}
	for {
		select {
		case <-ctx.Done():
			return
		case <-self.capRefresh:
		case <-time.After(capReadInterval):
		}
		self.readCapsOnce(ctx)
	}
}

// Reads the caps once with the latest client JWT and records the reading.
func (self *embedSession) readCapsOnce(ctx context.Context) {
	clientJwt := func() string {
		self.stateLock.Lock()
		defer self.stateLock.Unlock()
		return self.clientJwt
	}()
	reading, err := readOwnDataCap(ctx, self.httpClient, self.config.apiOrigin, clientJwt, self.clientId)
	select {
	case <-ctx.Done():
		// stopping: a canceled read is not a failed reading
		return
	default:
	}
	self.stateLock.Lock()
	defer self.stateLock.Unlock()
	self.caps.Record(reading, err)
}

// Stops the Device: closes the subscriptions, the device, then the manager.
// The final flush keeps a short run's last SDK log lines in the logs
// directory.
func (self *embedSession) Close() {
	for _, sub := range self.subs {
		sub.Close()
	}
	self.device.Close()
	self.manager.Close()
	sdk.FlushGlog()
}

// Keeps the refreshed credential, so the next start and the cap reads use a
// valid token.
func (self *embedSession) jwtRefreshed(clientJwt string) {
	func() {
		self.stateLock.Lock()
		defer self.stateLock.Unlock()
		self.clientJwt = clientJwt
	}()
	if err := saveClientJwt(self.config.stateDir, clientJwt); err != nil {
		// never print the token itself
		fmt.Fprintf(os.Stderr, "could not save the refreshed client credential: %v\n", err)
	}
}

// Ends the run: the server no longer accepts this client's credential.
func (self *embedSession) authLogout() {
	self.logoutOnce.Do(func() {
		close(self.logout)
	})
}

// Asks for a cap read; requests while one is pending coalesce.
func (self *embedSession) contractStatusChanged() {
	select {
	case self.capRefresh <- struct{}{}:
	default:
	}
}

// Saves refreshed client credentials.
type jwtRefreshListener struct {
	session *embedSession
}

// Saves the refreshed token.
func (self *jwtRefreshListener) JwtRefreshed(clientJwt string) {
	self.session.jwtRefreshed(clientJwt)
}

// Ends the run when the server rejects the client credential.
type authLogoutListener struct {
	session *embedSession
}

// Ends the run with a credential error.
func (self *authLogoutListener) AuthLogout() {
	self.session.authLogout()
}

// Reads the caps again when the contract status changes, for example when a
// cap stops new contracts.
type contractStatusListener struct {
	session *embedSession
}

// Asks for a cap read.
func (self *contractStatusListener) ContractStatusChanged(contractStatus *sdk.ContractStatus) {
	self.session.contractStatusChanged()
}