Pushed Messages

A machine that packs agents has a connection's messages pushed to it over HTTPS, or held for it, instead of a bridge polling them. Five commands do it, none of them run by lnk itself.

lnk-<connection> hook

A connection whose describe says pushed (lnk-telegram, lnk-slack). Reads link_connection_contract::pushed::Hooking as one JSON line on stdin ({"settings", "url", "secret"}, the connection's settings with its token) and points the connection's pushes at url, each carrying secret. Runs outside every sandbox, where the token is.

Each connection's secret

Telegram's secret is its secret_token. Slack signs with its own signing secret, in settings, which lnk agent connect slack doesn't keep: the caller adds signing_secret, and config_token to switch the app itself, used and never kept. Without the signing secret, Slack's hook fails and switches nothing.

What it prints

It prints Hooked ({"settings", "steps"?}): settings, what sift is handed, none of it secret (who may talk to the agent, the bot's id), and steps, what a person does on the connection's own pages when the module couldn't make the change itself.

Its exits

It exits 13 when the connection refused the webhook (link_connection_contract::WEBHOOK_REFUSED: it answered and said no to the address or its secret, as Telegram's setWebhook does), 11 when it refused the bot's token (TOKEN_REFUSED), and nonzero for any other failure. Slack's never refuses, falling back to steps when it can't switch the app.

lnk-<connection> unhook

The same connections. Reads Unhooking ({"settings"}) and turns the pushes off, so bridge polls or holds its socket again.

lnk-<connection> sift

A connection whose describe says pushed or held. Reads Sifting JSON lines until stdin closes, and writes a Verdict line for each, in order. It holds no token and calls nothing.

The lines it reads

A line is {"settings", "secret", "previous"?, "headers", "body", "shared"?}, the headers' names in lowercase, or {"settings", "say": {"chat", "text"}}. previous is the secret before secret while it rolls, taken beside it and sent only then (Sifting::secrets, for link_secretive::inbound).

The chats it's shared with

shared holds the chats on the connection the agent is shared with, by the connection's ids, as its spec's [access] message says when the push comes, never kept from hook, and sent only when there are some.

Drop

{"drop": {"status"}}: a wrong secret or signature, 401; a stranger's message, 200, so the connection doesn't push it again; a line it can't read, 400.

Answer

{"answer": {"status", "content_type", "body"}}: the connection's check of the address, or a say the connection takes in a push's own response, as Telegram's sendMessage.

Take

{"take": {"thread", "chat", "dedupe", "from"?}}, a message for the agent: its Link-Thread, its chat, and the connection's id for the push, the same on a retry. For a say, the machine sends it with send.

Who a message is from

from is member:<connection>:<user id>, set when the message is someone's in a chat the agent is shared with, not the owner's. Only a connection whose describe says share sets it, and only for a chat shared names; a machine that packs agents takes it only in a chat shared names.

The webhook module's

lnk-webhook-connection speaks sift alone, run by an agent's bridge for its webhooks (lnk agent webhook), which hands it a webhook's {"name", "from"} as settings (from link or github) and its secrets.

lnk-<connection> receive

The same connections as sift. Reads Taking ({"bridge", "update"}: a Bridge as bridge reads it, and the update pushed, its body as JSON or what hold gave) and answers it as bridge answers a message it polls, its endpoint http:// or unix:<socket>. It ends once the answer is sent.

Its exits

It exits 11 when the connection refused the bot's token (TOKEN_REFUSED), and 12 when it refused the answer itself (link_connection_contract::REPLY_REFUSED): the connection answered the send and said no, as it does for a chat gone or a bot blocked. A connection says the same of a request of the module's own it can't take, so a 12 isn't always the user's doing; any other failure is nonzero.

lnk-<connection> hold

A connection whose describe says held (lnk-discord), whose messages come only on a connection held open. Reads HoldLines until stdin closes, {"hold": {"key", "settings"}} (hold that bot's connection as key) or {"drop": "<key>"}. One process holds many bots, resuming a dropped connection where the connection allows. It answers and sends nothing.

What it writes

It writes a Held line for each message ({"key", "update"}) and for each connection up or down ({"key", "state": "up" | "down" | "refused"}), refused being down because the connection refused the bot's token. A reader takes a state it doesn't know as down, never up.