mesh-sdk/go/channel/channel.go

// Package channel holds the shapes of the two kinded benches a channel holds, `channel` (to show and say) and `intake`
// (to say what was chosen, and to ask a proof), and the subjects they travel on (novox/hq ADR 0259 §3). The router
// sends a channel a Message, and a channel says a Choice, a LinkAsked, a Failed or its Standing, or asks a Code's proof.
// Those benches are not defined whole, so their value layouts stay in mesh-sdk (novox/hq ADR 0625 §9, ADR 0627 §4);
// the operator-channel seat's own ask and warrant are its contract's and its client's, in mesh-contracts.
package channel

import "time"

// The benches (novox/hq ADR 0259 §3).
const (
	// ChannelSeat is the kinded bench a channel holds to show and say: its accepts carry the kind.
	ChannelSeat = "channel"
	// IntakeSeat is the kinded bench a channel holds to say what was chosen: its events and proofs carry
	// the kind.
	IntakeSeat = "intake"
)

// The work a channel takes, on ChannelSubject.
const (
	Show = "show" // a message offering answers
	Edit = "edit" // a message shown before, replaced
	Send = "send" // a message offering nothing
)

// ChannelSubject is where the router sends a channel of a kind its work.
func ChannelSubject(verb, kind string) string {
	return "mesh.seat." + ChannelSeat + ".accept." + verb + "." + kind
}

// What a channel says, on IntakeSubject.
const (
	Chosen = "choice" // a button tapped
	Link   = "link"   // somebody asked to be linked as the operator
)

// IntakeSubject is where a channel of a kind says what arrived.
func IntakeSubject(what, kind string) string {
	return "mesh.seat." + IntakeSeat + ".event." + what + "." + kind
}

// CodeProof is the one proof verb: a code the operator typed, carried by request and reply, never kept.
const CodeProof = "code"

// ProofSubject is where a channel of a kind asks a proof.
func ProofSubject(verb, kind string) string {
	return "mesh.seat." + IntakeSeat + ".proof." + verb + "." + kind
}

// Button is one answer a channel offers: its label and the router's one-time ticket for it.
type Button struct {
	Label  string `json:"label"`
	Ticket string `json:"ticket"`
}

// Message is the work a channel takes: shown with buttons (Show), shown again in place (Edit), or said
// (Send). Handle is the router's name for it, the same across a show and its edits; the channel keeps
// which of its own messages that is. The words are the router's, shown as given.
type Message struct {
	Handle  string   `json:"handle"`
	Title   string   `json:"title"`
	Body    string   `json:"body"`
	Buttons []Button `json:"buttons,omitempty"`
	// Note is the message's secondary words, after its body and its buttons: who asked and when, what each
	// answer does, when it expires, and the ask's Details. A channel shows it smaller, collapsed or set apart
	// where it can, and after the body where it cannot (novox/hq issue 639). A channel that bounds a message's
	// length cuts the body first and the note only when the title and the note alone do not fit, saying each
	// cut (novox/hq ADR 0347 §5).
	Note   string `json:"note,omitempty"`
	Urgent bool   `json:"urgent,omitempty"`
	Silent bool   `json:"silent,omitempty"`
	// Reply is the Choice or LinkAsked this answers, by its ID: the channel shows it where that was made.
	Reply string `json:"reply,omitempty"`
	// To is the account linked as the operator on this kind, for a channel that verifies its sender: where
	// the channel sends what is not a reply. The router's word, from its list; empty when none is linked.
	To string `json:"to,omitempty"`
	// Secret says the words carry something shown once (a link's code): the channel shows it and keeps no
	// copy of it — no state, no history of its own.
	Secret bool `json:"secret,omitempty"`
}

// Sender is who a channel's service says sent something: the account, the name it shows, and whether the
// service authenticated it. The router alone judges whether that is the operator.
type Sender struct {
	Identity      string `json:"identity"`
	Display       string `json:"display,omitempty"`
	Authenticated bool   `json:"authenticated"`
}

// Failed is a message a channel could not deliver: its handle, why, and whether trying again could help.
type Failed struct {
	Handle    string    `json:"handle"`
	Why       string    `json:"why"`
	Permanent bool      `json:"permanent,omitempty"`
	At        time.Time `json:"at"`
}

// Standing is what a channel says of itself, at least every five minutes and whenever it changes:
// whether it can send now, why not, and whether its edits notify nobody.
type Standing struct {
	Ready         bool      `json:"ready"`
	Why           string    `json:"why,omitempty"`
	EditsSilently bool      `json:"edits-silently,omitempty"`
	At            time.Time `json:"at"`
}

// What a channel says of its own delivery, on IntakeSubject.
const (
	FailedWhat   = "failed"
	StandingWhat = "standing"
)

// Choice is a button chosen on a channel.
type Choice struct {
	// ID is the channel's own for this arrival, unique, so the router acts on it once.
	ID     string    `json:"id"`
	Ticket string    `json:"ticket"`
	Handle string    `json:"handle,omitempty"`
	Sender Sender    `json:"sender"`
	At     time.Time `json:"at"`
}

// LinkAsked is somebody on a channel asking to be linked as the operator.
type LinkAsked struct {
	ID     string    `json:"id"`
	Sender Sender    `json:"sender"`
	At     time.Time `json:"at"`
}

// Code is a code a person typed on a channel, asked as a proof: never in an event, never kept.
type Code struct {
	Sender  Sender `json:"sender"`
	Code    string `json:"code"`
	Purpose string `json:"purpose"`
}

// ProofAnswer is the router's answer to a proof: whether it was taken, and words to say to the person.
type ProofAnswer struct {
	Accepted bool   `json:"accepted"`
	Words    string `json:"words"`
}