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
- func CheckCredentialShape(kind, token string) error
- func CredentialParts(kind, token string) []string
- func HTMLLineBreaks(h string) string
- func HostsFor(k Kind, server string) ([]string, error)
- func MatrixLogin(ctx context.Context, server, user, password string) (string, error)
- func Names() []string
- func NormalizeCode(text string) (string, bool)
- func SendTest(ctx context.Context, c Credential, api, chat, text string) error
- func Serve(ctx context.Context, in io.Reader, out io.Writer, logw io.Writer, cfg Config) error
- func ServerHost(server string) (string, error)
- func SlackManifest(name string) string
- func SlackTokens(credential string) (app, bot string, err error)
- type Config
- type Credential
- type Dropped
- type Format
- type FromRole
- type Inbound
- type Kind
- type Paired
- type Pairing
- type Part
- type Peer
- type Ready
- type Reply
- type Sent
- type ServiceError
- type Start
- type State
- type TelegramError
- type ToRole
- type Typing
- type Writer
Constants ¶
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.
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.
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).
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.
const (
DiscordAPI = "https://discord.com/api/v10"
)
The Discord API's addresses.
const MaxInboundText = 16 << 10
MaxInboundText bounds the text of one message the role passes on; a longer one is cut, and says so.
const MaxLine = 256 << 10
MaxLine bounds one line of the link either way.
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.
const RestInAgentry = "… The rest of this answer is in Agentry."
RestInAgentry ends the last part of an answer cut at MaxParts.
const SlackAPI = "https://slack.com/api"
SlackAPI is the Web API's address.
const TelegramAPI = "https://api.telegram.org"
TelegramAPI is the Bot API's address.
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 ¶
CheckCredentialShape refuses a credential that is not the kind's shape, before anything is sent with it.
func CredentialParts ¶ added in v0.7.14
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
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
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
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 NormalizeCode ¶
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 ¶
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
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
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
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
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 ¶
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.
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 ¶
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.
type Peer ¶
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 ¶
Ready is the role's first line, once the service took the credential: the account's own id and name there.
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 TelegramError ¶
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 ¶
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.