messenger

package
v0.7.12-dev.2 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 18 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 (
	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"

DroppedStale is a message older than the role passes on.

View Source
const KindTelegram = "telegram"

KindTelegram is Telegram, through a bot the person makes with BotFather.

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 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 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, kind, token, 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.

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

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.
	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.

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 {
	HTML  string
	Plain string
}

Part is one message of an answer: its HTML, and the same text plain, sent instead when the service cannot parse the HTML.

func Split

func Split(markdown string, limit int) (parts []Part, cut bool)

Split is an answer's messages 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, kind, token, 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 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 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