outbox

func Emit ¶

func Emit(ctx context.Context, tx pgx.Tx, table, kind, id, eventType string, payload map[string]any) error

Emit вставляет одну outbox-строку в произвольную таблицу с фиксированной схемой: (sequence_no BIGSERIAL PK, resource_kind TEXT, resource_id TEXT, event_type TEXT, payload JSONB, created_at TIMESTAMPTZ DEFAULT now()).

table — имя таблицы (например "vpc_outbox"). kind — тип ресурса ("Network", "Subnet", "Address", "RouteTable", "SecurityGroup"). id — ID ресурса (TEXT, поддерживает любой формат — UUID, короткий непрозрачный id и т.д.). eventType — "CREATED" | "UPDATED" | "DELETED". payload — произвольная map (сериализуется в JSONB).

Должна вызываться внутри pgx.Tx, в которой выполняется INSERT/UPDATE/DELETE целевой ресурсной таблицы — это обеспечивает атомарность outbox-write.

На каждый INSERT срабатывает trigger pg_notify('<channel>', sequence_no), который будит подписанных stream subscribers.

func EmitAnchored ¶

func EmitAnchored(ctx context.Context, tx pgx.Tx, table, kind, id, projectID, eventType string, payload map[string]any) error

EmitAnchored — то же, но с ПРОЕКТНЫМ ЯКОРЕМ в колонке `project_id`.

Почему отдельная функция, а не параметр у Emit ¶

Якорь — свойство ЖУРНАЛА, а не вызова: колонка либо есть в таблице, либо нет, и вставка в несуществующую колонку — отказ хранилища, а не пустое значение. Единая сигнатура заставила бы владельцев журналов без колонки передавать что-нибудь, и «что-нибудь» уезжало бы в SQL, который у них не исполнится.

Зачем якорь нужен КОЛОНКОЙ ¶

Общая форма подписки (`pkg/subscription`) несёт проектный якорь полем оболочки события и принимает по нему решение о показе — не обращаясь к предмету. Для события снятия это несущее: обращаться не к чему, а нагрузка снятия несёт один идентификатор. Владелец, у которого якорь только в нагрузке, отдаёт у снятий пустой якорь — то есть утверждение «предмет уровня аккаунта», — и подписка с осью проекта такие события молча не пропускает. Потребитель, снявший опрос, об удалении не узнаёт никогда.

Кто её зовёт — СПРАШИВАЕТСЯ У ДЕРЕВА, а не перечисляется здесь ¶

Здесь стоял поимённый перечень зовущих, и он пережил свой предмет: журнал, названный в нём среди «колонки не несут и зовут Emit», к тому дню колонку нёс и звал ЭТУ функцию. Направление ошибки было худшим из возможных — перечень ЗАНИЖАЛ, то есть посылал следующего владельца журнала брать безъякорную форму, а это ровно тот тихий отказ, о котором предупреждает раздел выше.

Рукописный перечень в общей библиотеке протухает молча и читается как доказательство, поэтому он снят, а не переписан на сегодняшнее число. Спрашивайте дерево — обе команды дают ответ за секунду:

git grep -n 'outbox.EmitAnchored(' -- services/ ':!*_test.go'   # кто зовёт якорную
git grep -n 'outbox.Emit('         -- services/ ':!*_test.go'   # кто зовёт безъякорную

Несёт ли КОНКРЕТНЫЙ журнал колонку якоря — вопрос к его миграциям, а не к вызывающему:

git grep -rn '<таблица> ADD COLUMN IF NOT EXISTS project_id' -- services/

Вызов этой библиотеки — НЕ единственная форма записи журнала в дереве, и перечислять прочие здесь значило бы завести второй рукописный перечень взамен снятого. Их перепись ВЫВОДИТСЯ обходом в internal/repohygiene/journalwriteforms.go: она печатает по каждой форме и то, сколько её экземпляров распознаватель нашёл в дереве вообще, поэтому «ноль» там отличимо от «не искали».

Почему функций всё-таки две ¶

Довод не зависит от того, кто их зовёт сегодня, и потому переживёт любой перечень: якорь — свойство ХРАНИЛИЩА, колонка либо есть, либо нет, и вставка в несуществующую колонку есть отказ базы. Две функции — не два языка об одном предмете, а две РАЗНЫЕ формы хранения, каждая названная вслух. Сведение журналов к одной форме заведено отдельным предметом; до него выбор функции диктует таблица, а не вкус вызывающего.

func SanitizeTable ¶

func SanitizeTable(table string) string

SanitizeTable квотирует имя таблицы (опц. схема-квалифицированное "schema.table") через pgx.Identifier — идентификатор экранируется библиотекой независимо от дисциплины вызывающего. Даже при контрактe «caller передаёт literal» это defense-in-depth: имя таблицы больше не может стать вектором statement-injection при interpolation в `INSERT INTO %s`.

Единый source-of-truth для всех outbox-подпакетов (reconciler/metrics), чтобы политика квотирования имён не расходилась между ними.

func StartQueueRetentionSweep ¶

func StartQueueRetentionSweep(
	ctx context.Context,
	db QueueExecer,
	cfg QueueRetentionConfig,
	rcfg retention.Config,
	log *slog.Logger,
) (*retention.Sweeper, error)

StartQueueRetentionSweep поднимает фоновую уборку доставленных строк очереди.

ОДНА строка в композиционном корне владельца — намеренно: шесть владельцев несут семь очередей одной формы с одним контрактом доставки, и всё, что у них могло бы разойтись, собрано здесь.

Отказывает, а не предупреждает: отказ означает негодные величины расписания либо объявление, при котором уборка небезопасна.