Einen Send-Provider schreiben

Ein Send-Provider ist ein Versandanbieter, der nicht Owlats eigener MTA ist: ein ESP, ein Relay, ein SMTP-Dienst. Owlat behandelt jeden von ihnen als Bundle — ein Sendepfad, ein Feedback-Pfad, eine Sending-Domain-Identität, Capability-Deklarationen und ein Formular für Zugangsdaten, die zusammen reisen — und nimmt dieses Bundle auf jeder der zwei Stufen mit demselben Vertrag entgegen.

Provider N+1 ist ein Package. Weder Routing, Dispatch, Retries, der Deliverability-Fallback, der Ramp-Controller, die Measurement-Ebene noch die UI für Zugangsdaten werden bearbeitet, um einen hinzuzufügen.

Beginnen Sie mit dem Scaffold:

owlat plugins create acme-relay --name @acme/owlat-relay --template send-provider

Das erzeugt ein vollständiges, komponierendes Bundle: alle drei ausführbaren Hälften, jedes Capability-Feld, das diese Stufe deklarieren darf, ein Formular für Zugangsdaten, das mit den von ihm geschriebenen Variablen verbunden ist, einen host-verifizierbaren Webhook-Vertrag sowie eine Testsuite je Hälfte. Übrig bleibt der Anteil Ihres Anbieters, an genau der Zeile mit TODO markiert, an die er gehört.

Das Scaffold landet innerhalb des Owlat-Checkouts, in dem Sie es ausführen — examples/plugins/<id>, sofern Sie kein --dir übergeben, und niemals außerhalb des Workspace. Deshalb ist die erzeugte package.json private und ihre Dependencies sind workspace:*- und catalog:-Spezifikatoren: Das Package ist an diesen Checkout gebunden, bis Sie es herauslösen. Das Veröffentlichen ist der letzte Schritt dieses Herauslösens, und die erzeugte README listet die vier Dinge auf, aus denen dieser Schritt besteht.

Das Bundle

Die beiden optionalen Hälften werden nicht von einem Boolean begleitet. Das Deklarieren eines webhook ist das hasProviderFeedback: true des Katalogs für Ihre Art, und das Deklarieren einer domainIdentity ist dessen domainVerification: 'api'. Eine Tatsache, einmal ausgesprochen: Ein Boolean daneben könnte nur jemals dem Modul widersprechen, das sie implementiert.

Unten steht das Manifest, um das herum ein Bundle gebaut wird — die src/manifest.ts des Scaffolds mit beantworteten Anbieter-TODOs. Sie erweitert die Datei, die das minimale Manifest beginnt, importiert also nur die Capability-Konstante, die sie hinzufügt; definePlugin ist bereits im Scope. Das Scaffold leitet jeden Variablennamen und Header aus Ihrer Plugin-Id ab (acme-relay ⇒ PLUGIN_ACME_RELAY_API_KEY, x-acme-relay-signature), und genau das sind die Namen hier.

import { PLUGIN_SEND_TRANSPORT_CAPABILITY } from '@owlat/plugin-kit';

export const acmeRelayPlugin = definePlugin({
    id: 'acme-relay',
    version: '1.0.0',
    capabilities: [PLUGIN_SEND_TRANSPORT_CAPABILITY],
    // Deployment-wide: the plugin is off until both are set. The signing secret
    // belongs HERE and not on the transport — without it the feedback route can
    // verify nothing and answers every delivery 503.
    flag: {
        default: false,
        requiredEnvVars: ['ACME_RELAY_ENABLED', 'PLUGIN_ACME_RELAY_WEBHOOK_SECRET'],
    },
    contributes: {
        sendTransports: [
            {
                id: 'relay',
                label: 'Acme Relay',
                module: { exportPath: './convex/transport' },
                retryDelays: [1_000, 5_000],
                // THIS TRANSPORT's own configuration: resolved per named instance
                // (`PLUGIN_ACME_RELAY_API_KEY__EU` for `plugin.acme-relay.relay#eu`) and
                // handed to `send` keyed by the base name.
                requiredEnvVars: ['PLUGIN_ACME_RELAY_API_KEY'],
                optionalEnvVars: ['PLUGIN_ACME_RELAY_REGION'],
                credentialFields: [
                    {
                        kind: 'secret',
                        key: 'apiKey',
                        label: 'API key',
                        required: true,
                        envVar: 'PLUGIN_ACME_RELAY_API_KEY',
                    },
                    {
                        kind: 'select',
                        key: 'region',
                        label: 'Sending region',
                        options: [
                            { value: 'eu', label: 'Europe' },
                            { value: 'us', label: 'United States' },
                        ],
                        default: 'eu',
                        envVar: 'PLUGIN_ACME_RELAY_REGION',
                    },
                ],
                // `no` is the only value this tier may declare.
                supportsCustomReturnPath: 'no',
                messageIdSource: 'provider',
                deduplicatesOnIdempotencyKey: false,
                // Declaring a webhook IS `hasProviderFeedback: true` for this kind.
                webhook: {
                    module: { exportPath: './convex/webhook' },
                    signature: {
                        header: 'x-acme-relay-signature',
                        algorithm: 'hmac-sha256',
                        encoding: 'hex',
                        secretEnvVar: 'PLUGIN_ACME_RELAY_WEBHOOK_SECRET',
                        // REQUIRED: without replay provisions a captured request verifies
                        // forever. The host signs `<timestamp>.<rawBody>`.
                        replay: { timestampHeader: 'x-acme-relay-timestamp', toleranceSeconds: 300 },
                    },
                },
                // Declaring an identity IS `domainVerification: 'api'` for this kind.
                domainIdentity: { module: { exportPath: './convex/domainIdentity' } },
            },
        ],
    },
});

Alles Ausführbare liegt an einem module.exportPath, den Ihr Package exportiert, und jedes davon wird als Default-Export dieses Moduls importiert — ebenso wie das Manifest an Ihrem Package-Root. Die Codegen verifiziert jeden Pfad, ohne ihn auszuführen; der Host importiert das Modul erst, wenn ein Versand, eine Zustellung oder eine Identitätsprüfung es tatsächlich benötigt. Exportieren Sie zusätzlich gern benannt, aber ein Modul mit ausschließlich benanntem Export komponiert zu einem Registry-Eintrag, dessen Modul undefined ist — und der erste Versand ist dann dasjenige, das es herausfindet. Das Scaffold erzeugt beides.

Die Provider-Checkliste, auf beiden Stufen

Dieselben sechs Schritte, auf welcher Stufe Sie auch sind. Nichts sonst — durchgesetzt von den Konformitäts-Suites, die über Katalogarten iterieren statt über eine Liste, und von der lint:providers-Ratsche, die jeden Vergleich gegen ein Provider-Art-Literal außerhalb eines Adapter-Ordners fehlschlagen lässt.

Die Core-Spalte unten ist eine Zusammenfassung. Send-Provider → die Provider-N+1-Checkliste ist die kanonische Liste der Core-Stufe, mit den exakten Dateipfaden, den Compile-Zeit-Schutzmechanismen hinter jedem Schritt und dem einen optionalen Schritt, den diese Tabelle nicht enthält.

Auf keiner der beiden Stufen ist eine Änderung an Routing, Dispatch, Ramp, Measurement oder Setup-Wizard erforderlich. Wenn Sie dabei sind, eine vorzunehmen, fehlt die Capability, die Sie brauchen, im Vertrag — das ist eine Änderung am Vertrag, nicht an Ihrem Bundle.

Das Einzige, was eine Core-Art optional ergänzen darf, sind UI-Formulierungen: apps/web führt Partial-Override-Maps für das Label eines Transports, seinen DNS-Hinweisabsatz und seinen Picker-Text (Schritt 7 auf der kanonischen Liste). Eine Art ohne Zeile rendert aus ihrem Katalogeintrag — nichts bricht und nichts bleibt leer —, schreiben Sie also nur dann eine, wenn diese Oberfläche Ihren Provider anders formulieren soll. Eine Plugin-Art hat dazu überhaupt keinen entsprechenden Schritt: Diese Maps sind über Core-Arten adressiert, und ein Bundle wird durch sein eigenes label und seine credentialFields beschrieben.

Semantik der Capabilities

Jedes Feld unten ist optional, und jedes hat denselben fail-closed-Default, den ein Core-Eintrag bekäme, der es weglässt, sodass ein gegen einen älteren Vertrag geschriebenes Manifest exakt so komponiert wie zuvor.

Konfiguration und benannte Instanzen

requiredEnvVars auf der Contribution ist das, was eine Instanz Ihres Transports benötigt. Es zu deklarieren ist das, was benannte Instanzen möglich macht: Ein Deployment kann plugin.acme-relay.relay#eu betreiben, das PLUGIN_ACME_RELAY_API_KEY__EU liest, und der Host übergibt Ihrem send genau die Werte dieser Instanz, adressiert über den Basisnamen, den Ihr Manifest geschrieben hat. Lesen Sie sie aus dem config-Argument — ein Modul, das process.env liest, löst die Zugangsdaten der Deployment-Default-Instanz auf, an welche Id der Versand auch adressiert war.

Namen unterliegen einer Regel: PLUGIN_-präfigiert, Großbuchstaben, kein __ (das ist der Instanz-Trenner) und kein abschließender _. Die flag.requiredEnvVars des Plugins selbst sind ein anderer Scope — ein deploymentweiter Schalter, der ohne Suffix gelesen wird — und die beiden Listen dürfen sich nicht überschneiden.

optionalEnvVars wird ohne mindestens eine erforderliche Variable abgelehnt: Ein Transport, dessen gesamte Konfiguration optional ist, hat keine Zugangsdaten pro Instanz aufzulösen, sodass jede benannte Instanz davon gegen eine leere Anforderungsliste bewertet würde.

Das Formular für Zugangsdaten

credentialFields sind typisierte Deskriptoren in demselben Vokabular, das das settingsSchema der Plattform verwendet — string, secret, number, boolean, select —, sodass ein einziger Renderer Ihre Zugangsdaten so zeichnet, wie er die eines Core-Providers zeichnet. Sie sind rein beschreibend: Nichts davon entscheidet, was ein Versand liest. Das envVar jedes Felds muss eine Variable sein, die dieser Transport deklariert hat, abgeglichen mit dem required des Felds selbst — und genau das verhindert, dass ein gerendertes Formular nach einer Variable fragt, die kein Versand liest, oder eine weglässt, die den Transport gatet.

Sicherheitserwartungen an den Webhook

Ihr Feedback-Modul parst. Es entscheidet niemals, ob ein Request authentisch ist. Bis es läuft, hat der Host bereits:

1. ein Rate-Limit-Token pro Plugin verbraucht — der eine Schreibvorgang, den ein unbewiesener Aufrufer auslöst, und zwar zuerst, weil ein Limiter, der nicht aufzeichnet, nicht limitieren kann;
2. die Route über die Plugin-Id aufgelöst (POST /webhooks/plugin/<pluginId>) und für eine unbekannte mit 404 geantwortet, bevor ein einziges Byte des Bodys gelesen wurde;
3. die Größe des Bodys begrenzt;
4. Ihren deklarierten HMAC über <timestamp>.<rawBody> in konstanter Zeit neu berechnet und mit dem von Ihnen benannten Header verglichen;
5. einen Zeitstempel abgelehnt, der weiter von jetzt entfernt ist als Ihre deklarierte Toleranz;
6. die Capability-Gewährung des Operators unter einer eigenen auditierten Operation erneut geprüft;
7. eine Zustellung abgelehnt, deren Signatur-Digest er bereits akzeptiert hat.

Contribution-Referenz → Feedback-Webhook ist die normative Liste dessen, was der webhook-Block enthalten muss — die Felder, die Toleranz-Obergrenze, in welchen der beiden Variablen-Scopes das Secret gehört und wie viele Webhooks ein Plugin deklarieren darf. Das ist die Seite, gegen die Sie Ihr Manifest schreiben; dieser Abschnitt erklärt, warum jede dieser Regeln existiert und was es kostet, sie falsch zu machen:

• signature ist erforderlich. Ein Webhook ohne sie scheitert an der Manifest-Validierung. Dieser Endpoint ist per Design unauthentifiziert und zum Internet hin offen; ein unverifizierter wäre ein offener Schreibpfad in den Zustellungsdatensatz.
• replay-Vorkehrungen sind ebenfalls erforderlich. Ein HMAC allein über den Body beweist die Herkunft und sonst nichts — dieselben abgefangenen Bytes verifizieren für immer. Erst das Einbinden eines Zeitstempels in den signierten String und das Begrenzen seines Alters sorgt dafür, dass eine Zustellung einmal passiert. Die Obergrenze dieses Fensters gehört dem Kit, nicht Ihnen; wählen Sie die kleinste, die die Retries Ihres Providers vertragen, deutlich darunter.
• Das Signier-Secret gatet das Plugin, nicht den Transport. Ohne es kann die Route nichts verifizieren und beantwortet jede Zustellung mit 503 — und eine Serie von Nicht-2xx ist genau das, was einen Provider dazu bringt, Ihren Endpoint zu deaktivieren —, deshalb darf das Plugin ohne es nicht aktivierbar sein. Darum wird es in dem Scope deklariert, den ein Deployment ohne Suffix liest, statt neben Ihren Zugangsdaten pro Instanz.
• Die Routen-Oberfläche ist über die Plugin-Id adressiert, sodass ein zweiter Webhook im selben Plugin nie ansprechbar wäre; ein Manifest, das einen deklariert, wird abgelehnt statt stillschweigend ignoriert.
• Rohe Payloads werden nicht aufbewahrt, sofern Sie es nicht verlangen. Die Payload eines Dritten kann Empfängerinhalte tragen, die dieses Deployment nie aufbewahren wollte, weshalb die Aufbewahrung Ihre explizite Entscheidung ist statt der Default der Pipeline.

Innerhalb des Moduls: Geben Sie für einen Verifikations-Ping aus der Konsole und für Ereignisarten, die Owlat nicht konsumiert, das leere Array zurück — ein 400 würde Ihren Provider dazu bringen, sie für immer erneut zuzustellen — und werfen Sie bei einem Body, den Sie nicht lesen können. Lesen Sie den Zeitstempel eines Ereignisses nur für die Arten, die Sie tatsächlich konsumieren: Ein Engagement-Ereignis, das Sie ignorieren, lässt das Feld womöglich ganz weg, und es oberhalb Ihres Art-Switches zu validieren reißt den gesamten Batch mit hinunter. Importieren Sie keine Node-Builtins: Das Modul wird vom HTTP-Router geladen.

Sending-Domain-Identität

Ihr Identitätsmodul meldet Beobachtungen, niemals ein Verdikt: ob der Provider die Inhaberschaft bestätigt hat, seine Verdikte zu den veröffentlichten SPF- und DKIM-Records, die DKIM-Selektoren, unter denen er signiert, und die SPF-Mechanismen, für die er eine Autorisierung braucht. Der Host leitet den Status daraus ab, sodass "verifiziert" auf jeder Relay-Stufe dasselbe bedeutet und ein Modul eine Domain nicht als verifiziert melden kann, während es uns mitteilt, dass ihr DKIM ungültig ist. Die Frische-Grenze dieses Nachweises ist eine Host-Konstante, kein Manifest-Feld.

Unterscheiden Sie die drei Ergebnisse, denn die Schreibregeln des Hosts sind für jedes andere: ok ist das einzige, das das Alter des Nachweises auffrischt, auth_failed verurteilt ein Credential, ohne die bereits gespeicherten DNS-Verdikte zu überschreiben, und unavailable — als das auch ein geworfener Fehler gelesen wird — ändert nichts außer dem Retry.

Geben Sie Ihre DKIM-Selektoren zurück, wann immer Sie sie kennen. Eine leere Liste bedeutet "wir können die Signier-Identität dieser Domain nicht beschreiben", was der Alignment-Pre-Flight für Dual-Transport als Halt für die Ramp liest statt als geöffnetes Gate.

Was das Scaffold Ihnen gibt

Jedes Template schreibt dasselbe Package-Skelett aus drei Dateien — package.json (private, mit der Export-Map, gegen die die Modulpfade Ihres Manifests geprüft werden), tsconfig.json und vitest.config.ts. Darüber hinaus erzeugt owlat plugins create <id> --template send-provider:

Das erzeugte Bundle ist keine Skizze: Es komponiert, und Owlats eigenes Konformitäts-Gate treibt die Ausgabe des Generators — unverändert — bei jedem CI-Lauf durch die ausgelieferten Routing-, Dispatch-, Feedback- und Identitätsmodule.

Wie es weitergeht

• Contribution-Referenz — der sendTransports-Bucket neben jedem anderen Bucket, mit den Modulverträgen in voller Länge.
• Capabilities & Vertrauen — was send:transport gewährt und wie ein Operator es widerruft.
• Die owlat-plugins-CLI — create, add, remove, codegen.
• Send-Provider — der Katalog der Core-Stufe und die Capability-Tabelle pro Provider.