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 Names() []string
- func NormalizeCode(text string) (string, bool)
- func SendTest(ctx context.Context, kind, token, api, chat, text string) error
- func Serve(ctx context.Context, in io.Reader, out io.Writer, logw io.Writer, cfg Config) error
- type Config
- type Dropped
- type FromRole
- type Inbound
- type Kind
- type Paired
- type Pairing
- type Part
- type Peer
- type Ready
- type Reply
- type Sent
- 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 ( 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"
DroppedStale is a message older than the role passes on.
const KindTelegram = "telegram"
KindTelegram is Telegram, through a bot the person makes with BotFather.
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 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 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 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.
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 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 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.
Hosts []string
// 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
}
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: its HTML, and the same text plain, sent instead when the service cannot parse the HTML.
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 Start ¶
type Start struct {
Kind string `json:"kind"`
Token string `json:"token"`
Peer *Peer `json:"peer,omitempty"`
}
Start is the supervisor's first line: the kind, the account's credential 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.