messenger

package
v0.7.39-dev.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package messenger is the messenger role of the runner image: the one container that holds a messenger account's credential and its connection to that messaging service, for a persistent agent the person can talk to from there. It reaches the service's own hosts through an allowlisting relay and nothing else, and it talks to the agent's supervisor over its standard input and output, which carry messages, typing and delivery reports and nothing else: no command reaches the agent through it.

Part of the embedded runner-image build context: stdlib-only, enforced by a test in the parent package.

Index

Constants

View Source
const (
	DroppedUnpaired  = "unpaired"     // from a sender who is not paired
	DroppedNotDirect = "not-direct"   // in a group or a channel
	DroppedNoText    = "no-text"      // a sticker, a photo, a voice note
	DroppedCommand   = "command"      // the service's own command (/start)
	DroppedPairings  = "pairing-rate" // more pairing codes than the role passes on
)

The reasons a message is dropped.

View Source
const (
	KindTelegram = "telegram"
	KindDiscord  = "discord"
	KindSlack    = "slack"
	KindMatrix   = "matrix"
)

The kinds: Telegram, through a bot the person makes with BotFather; Discord, through a bot of an application the person makes in Discord's developer portal; Slack, through an app the person makes in their workspace from the manifest Agentry gives (SlackManifest); and Matrix, through an account on any homeserver.

View Source
const (
	CodeAlphabet = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
	CodeLength   = 8
)

The pairing code a person sends from their own account: CodeLength characters of CodeAlphabet, which leaves out the ones read alike (0 and O, 1 and I and L).

View Source
const (
	DroppedStale     = "stale"
	DroppedEncrypted = "encrypted"
)

DroppedStale is a message older than the role passes on, and DroppedEncrypted one encrypted end to end, which the role cannot read.

View Source
const (
	DiscordAPI = "https://discord.com/api/v10"
)

The Discord API's addresses.

View Source
const MaxInboundText = 16 << 10

MaxInboundText bounds the text of one message the role passes on; a longer one is cut, and says so.

View Source
const MaxLine = 256 << 10

MaxLine bounds one line of the link either way.

View Source
const MaxParts = 5

MaxParts is the most messages one answer is sent as; an answer longer than that many ends by saying the rest is in Agentry.

View Source
const RestInAgentry = "… The rest of this answer is in Agentry."

RestInAgentry ends the last part of an answer cut at MaxParts.

View Source
const SlackAPI = "https://slack.com/api"

SlackAPI is the Web API's address.

View Source
const TelegramAPI = "https://api.telegram.org"

TelegramAPI is the Bot API's address.

View Source
const TokenRefused = "the service refused the account's credential"

TokenRefused begins the error of a credential the service does not know, in the role's state and in Serve's error alike.

Variables

This section is empty.

Functions

func CheckCredentialShape

func CheckCredentialShape(kind, token string) error

CheckCredentialShape refuses a credential that is not the kind's shape, before anything is sent with it.

func CredentialParts added in v0.7.14

func CredentialParts(kind, token string) []string

CredentialParts are the values a credential is made of, each masked on its own wherever it would appear: a Slack credential's two tokens, any other credential whole.

func HTMLLineBreaks added in v0.7.14

func HTMLLineBreaks(h string) string

HTMLLineBreaks is FormatHTML for a Matrix client, which collapses a line break outside a preformatted block as a browser does: each such break becomes <br>.

func HostsFor added in v0.7.14

func HostsFor(k Kind, server string) ([]string, error)

HostsFor are the host:port pairs an account of k reaches: the kind's own, or the server the account names.

func MatrixLogin added in v0.7.14

func MatrixLogin(ctx context.Context, server, user, password string) (string, error)

MatrixLogin signs in to the homeserver at server as user with password and is the new session's access token: how a person adds a Matrix account without finding a token. It runs on the person's own computer, never in the role, and the password is never kept.

func Names

func Names() []string

Names are the keys of the messengers this build knows.

func NormalizeCode

func NormalizeCode(text string) (string, bool)

NormalizeCode is text as a pairing code, upper case, without the spaces and dashes a person may type in it, and ok when it is one.

func SendTest

func SendTest(ctx context.Context, c Credential, api, chat, text string) error

SendTest sends text to chat on the account, plain.

func Serve

func Serve(ctx context.Context, in io.Reader, out io.Writer, logw io.Writer, cfg Config) error

Serve is the role: it reads its start from in, connects to the service with the credential it carries, writes ready to out, then passes on the paired person's messages and sends the replies it is given until in ends or ctx does. logw gets its own errors, never a credential or a message.

func ServerHost added in v0.7.14

func ServerHost(server string) (string, error)

ServerHost is the host:port of an account's own server, given as an https:// address with no path, query or user: a Matrix homeserver's client address (https://matrix.example.org). The role's relay dials public addresses alone, so an address that is not one is refused; http:// is taken for this computer alone, as a test's server is.

func SlackManifest added in v0.7.14

func SlackManifest(name string) string

SlackManifest is the app manifest a person creates their Slack app from: a bot that takes direct messages in its Messages tab over Socket Mode, with the scopes that needs and no other.

func SlackTokens added in v0.7.14

func SlackTokens(credential string) (app, bot string, err error)

SlackTokens are the two tokens of a Slack credential.

Types

type Config

type Config struct {
	// Proxy is the relay's http:// address, the role's only route out.
	Proxy string
	// API is the service's address; empty is its own (a test's server
	// otherwise).
	API string
}

Config is how the role reaches its service.

type Credential added in v0.7.14

type Credential struct {
	Kind   string
	Token  string
	Server string
}

Credential is a messenger account's credential, as the keychain keeps it, and the account's own server where its kind has one.

type Dropped

type Dropped struct {
	Reason string `json:"reason"`
}

Dropped is a message the role did not pass on, and why: never who sent it or what it said.

type Format added in v0.7.14

type Format int

Format is how a service is written to.

const (
	// FormatHTML is the subset of HTML Telegram's Bot API parses, which a
	// Matrix client renders too.
	FormatHTML Format = iota
	// FormatMarkdown is Discord's Markdown, which takes a model's own
	// marks as they are.
	FormatMarkdown
	// FormatSlack is Slack's mrkdwn: *bold*, _italic_, ~strike~ and
	// <url|text> links, with &, < and > escaped.
	FormatSlack
)

type FromRole

type FromRole struct {
	Ready   *Ready   `json:"ready,omitempty"`
	Inbound *Inbound `json:"inbound,omitempty"`
	Pairing *Pairing `json:"pairing,omitempty"`
	Dropped *Dropped `json:"dropped,omitempty"`
	Sent    *Sent    `json:"sent,omitempty"`
	State   *State   `json:"state,omitempty"`
}

FromRole is one line the role writes.

func ReadFromRole

func ReadFromRole(line []byte) (FromRole, error)

ReadFromRole decodes one line the role wrote, strictly.

type Inbound

type Inbound struct {
	// ID is the message's id in its chat, which grows message by message.
	ID     int64  `json:"id,omitempty"`
	Chat   string `json:"chat"`
	Sender string `json:"sender"`
	Text   string `json:"text"`
	// Cut says the text was longer than MaxInboundText.
	Cut bool `json:"cut,omitempty"`
}

Inbound is a message from the paired person.

type Kind

type Kind struct {
	// Name is the kind's key: "telegram", as a roster id says it
	// (messenger:telegram) and the runner policy's messengerKinds name it.
	Name string
	// Title is how a person is shown it.
	Title string
	// Hosts are the host:port pairs the role reaches, through its relay,
	// and nothing else. A kind whose account names its own server (NamesServer)
	// has none: its relay reaches that server alone (HostsFor).
	Hosts []string
	// NamesServer says each account is on a server the person names (a
	// Matrix homeserver), which is the one host its role reaches.
	NamesServer bool
	// MaxMessage is the most characters one message there holds.
	MaxMessage int
	// EndToEnd says the service encrypts a conversation end to end, so it
	// cannot read the messages it carries.
	EndToEnd bool
	// Account is how the consent names the account the agent uses there.
	Account string
	// Format is how an answer is written there.
	Format Format
	// Typing says the service lets the account show that it is typing.
	Typing bool
}

Kind is one messaging service a persistent agent can be reached on: what the consent says of it, the hosts its role reaches, how long one message may be and how an answer is written there. One table, read by the consent, the relay and the role.

func Lookup

func Lookup(name string) (Kind, bool)

Lookup is the kind named name, case not mattering.

type Paired

type Paired struct {
	Peer *Peer `json:"peer,omitempty"`
}

Paired names the person paired from now on, or none.

type Pairing

type Pairing struct {
	Chat   string `json:"chat"`
	Sender string `json:"sender"`
	Code   string `json:"code"`
}

Pairing is a pairing code an unpaired sender sent in a direct message: the supervisor alone knows whether it is the code it showed.

type Part

type Part struct {
	Rich  string
	Plain string
}

Part is one message of an answer: in the service's format, and the same text plain, sent instead where the service cannot parse the format and beside it where the service takes both.

func SplitAs added in v0.7.14

func SplitAs(f Format, markdown string, limit int) (parts []Part, cut bool)

SplitAs is an answer's messages in format f for a service whose messages hold at most limit characters: at most MaxParts of them, the last ending with RestInAgentry when the answer is longer, and cut says it was.

type Peer

type Peer struct {
	Sender string `json:"sender"`
	Chat   string `json:"chat"`
}

Peer is the person's own account on the messenger, paired with the agent: the sender the role passes messages from, and the chat its replies go to.

type Ready

type Ready struct {
	Account string `json:"account"`
	Name    string `json:"name,omitempty"`
}

Ready is the role's first line, once the service took the credential: the account's own id and name there.

func Check

func Check(ctx context.Context, c Credential, api string) (Ready, error)

Check asks the service who the account is, as the role does when it starts: the account's id and name there. api is the service's address, empty for its own.

type Reply

type Reply struct {
	ID   uint64 `json:"id"`
	Chat string `json:"chat"`
	Text string `json:"text"`
}

Reply is an answer for the paired person's chat. ID names its Sent report.

type Sent

type Sent struct {
	ID    uint64 `json:"id"`
	Parts int    `json:"parts,omitempty"`
	Cut   bool   `json:"cut,omitempty"`
	Error string `json:"error,omitempty"`
}

Sent reports a Reply: how many messages it went as, whether it was cut at MaxParts, or why it was not sent.

type ServiceError added in v0.7.14

type ServiceError struct {
	Service string
	Method  string
	Code    int
	// Description is the service's own words, without the credential.
	Description string
	After       time.Duration
}

ServiceError is a service's refusal of a request.

func (*ServiceError) Error added in v0.7.14

func (e *ServiceError) Error() string

type Start

type Start struct {
	Kind   string `json:"kind"`
	Token  string `json:"token"`
	Server string `json:"server,omitempty"`
	Peer   *Peer  `json:"peer,omitempty"`
}

Start is the supervisor's first line: the kind, the account's credential, the account's own server where the kind has one (a Matrix homeserver's https:// address), and the paired person, if any.

type State

type State struct {
	Connected bool   `json:"connected"`
	Error     string `json:"error,omitempty"`
}

State is the connection's state as it changes: connected, or why not.

type TelegramError

type TelegramError struct {
	Method      string
	Code        int
	Description string
	RetryAfter  int
}

TelegramError is the Bot API's refusal of a request.

func (*TelegramError) Error

func (e *TelegramError) Error() string

type ToRole

type ToRole struct {
	Start  *Start  `json:"start,omitempty"`
	Reply  *Reply  `json:"reply,omitempty"`
	Typing *Typing `json:"typing,omitempty"`
	Paired *Paired `json:"paired,omitempty"`
}

ToRole is one line the supervisor writes.

func ReadToRole

func ReadToRole(line []byte) (ToRole, error)

ReadToRole decodes one line the supervisor wrote, strictly.

type Typing

type Typing struct {
	Chat string `json:"chat"`
}

Typing shows the paired person's chat that the agent is answering.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer writes frames as lines, one at a time.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter writes frames to w.

func (*Writer) Write

func (w *Writer) Write(frame any) error

Write writes one frame as a line.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL