httpgeneric

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package httpgeneric is the generic HTTP adapter (spec 5.2). It sends through any HTTP API described by a mapping instead of Go code: a request template (method, URL, headers and a JSON body with Liquid-style fields), where the response carries the provider's message id, and how the provider's webhooks are authenticated and read.

A mapping is the "http" object of an HTTP adapter's manifest — the format the Adapters tab saves into installed_adapters and that community manifests ship:

{"method": "POST", "url": "https://api.example-esp.com/v1/messages",
 "headers": {"Authorization": "Bearer {{ secrets.api_key }}"},
 "body": "{\"from\": \"{{ sender }}\", \"to\": \"{{ recipient }}\", \"subject\": \"{{ subject }}\", \"html\": \"{{ html }}\", \"headers\": {{ headers_json }}}",
 "message_id_path": "$.data.id",
 "webhook_mapping": "status",
 "webhook": {"auth": "hmac", "signature_header": "X-Signature"}}

A provider connected through the adapter keeps its mapping in its settings ({"http": {…}}), or is opened from an installed manifest with FromManifest. docs/adapters.md documents every field.

Index

Constants

View Source
const Adapter = "httpgeneric"

Adapter is the registry key.

Variables

This section is empty.

Functions

func CommunityDescriptor

func CommunityDescriptor(key, name, version, maintainer string, raw []byte) (providers.Descriptor, error)

CommunityDescriptor describes an installed HTTP adapter for the catalog and the connect flow, with a constructor that opens connections from the stored manifest.

func Descriptor

func Descriptor() providers.Descriptor

Descriptor describes the adapter for the catalog.

func FromManifest

func FromManifest(raw []byte, cfg providers.Config) (providers.Provider, error)

FromManifest builds the adapter for a provider connected through an installed HTTP adapter: the mapping, terms and pricing come from the manifest, the connection values and secrets from cfg.

func New

New builds the adapter from a connected provider whose settings hold the mapping ({"http": {…}}).

func SampleMessage

func SampleMessage() providers.Message

SampleMessage is the message "Test with a sample message" renders.

Types

type CheckSpec

type CheckSpec struct {
	URL string `json:"url"`
	// Headers default to the send request's headers (its authentication).
	Headers map[string]string `json:"headers,omitempty"`
}

CheckSpec is a GET request that succeeds (2xx) while the credentials and the API are fine ("https://api.example-esp.com/v1/account").

type Checked

type Checked struct {
	*Provider
}

Checked is the adapter for a mapping with a check request: it also implements providers.Verifier, so credentials are checked at connect time and the health job probes the API. A mapping without one has no Verify: a probe that can't fail would hide an outage.

func (*Checked) Verify

func (c *Checked) Verify(ctx context.Context) (providers.Quota, error)

Verify implements providers.Verifier with the mapping's check request.

type FieldError

type FieldError struct {
	Field   string
	Message string
}

FieldError is a mapping problem with the field it concerns.

func (*FieldError) Error

func (e *FieldError) Error() string

func (*FieldError) FieldName

func (e *FieldError) FieldName() string

FieldName is the mapping field an error is about ("body", "headers", "webhook.auth"), for forms that show errors next to the field.

type Manifest

type Manifest struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Maintainer   string   `json:"maintainer"`
	Kind         string   `json:"kind"`
	Capabilities []string `json:"capabilities,omitempty"`
	SourceURL    string   `json:"source_url,omitempty"`
	Terms        *Terms   `json:"terms,omitempty"`
	// Pricing is the provider's pricing model ("$0.80 per 1,000").
	Pricing string  `json:"pricing,omitempty"`
	HTTP    Mapping `json:"http"`
}

Manifest is an installed HTTP adapter's manifest.json (the installed_adapters.manifest column).

func ParseManifest

func ParseManifest(raw []byte) (Manifest, error)

ParseManifest reads and validates an HTTP adapter's manifest.

type Mapping

type Mapping struct {
	// Method is POST (default), PUT or PATCH.
	Method string `json:"method,omitempty"`
	// URL is https:// (http:// only for a loopback address). Placeholders may
	// appear in the path and query, never in the host.
	URL string `json:"url"`
	// Headers are header templates ("Bearer {{ secrets.api_key }}").
	// Content-Type defaults to application/json.
	Headers map[string]string `json:"headers,omitempty"`
	// Body is the JSON request body template.
	Body string `json:"body"`
	// MessageIDPath is the JSONPath of the provider's message id in a 2xx
	// response body ("$.data.id"); MessageIDHeader names a response header
	// that carries it instead ("X-Message-Id"). Without either, the
	// ReputeCast message id stands in for it.
	MessageIDPath   string `json:"message_id_path,omitempty"`
	MessageIDHeader string `json:"message_id_header,omitempty"`
	// ErrorCodePath and ErrorMessagePath read the provider's error code and
	// message from a failed response ("$.error.code", "$.error.message").
	ErrorCodePath    string `json:"error_code_path,omitempty"`
	ErrorMessagePath string `json:"error_message_path,omitempty"`
	// WebhookMapping is "status" (the payload's status field says
	// delivered, bounced, complained…; the default) or "jsonpath" (the
	// paths and type map in Webhook).
	WebhookMapping string `json:"webhook_mapping,omitempty"`
	// Webhook says how webhook requests are authenticated and read.
	Webhook WebhookSpec `json:"webhook,omitzero"`
	// Check is an optional read-only request ReputeCast makes to check the
	// credentials at connect time and the API's health every minute.
	// Without it, health comes from send results alone.
	Check *CheckSpec `json:"check,omitempty"`
	// Fields are the connection values the templates read beyond the
	// adapter's own (secrets.api_key, secrets.webhook_signing_key): a field
	// marked secret is read as secrets.<key>, others as settings.<key>.
	Fields []providers.Field `json:"fields,omitempty"`
}

Mapping describes one provider's HTTP API. JSON names follow the manifest's "http" object.

func (Mapping) Validate

func (m Mapping) Validate() error

Validate checks a mapping: method, URL, header names, that the body template renders to JSON, and the JSONPaths. Errors are sentences that can be shown next to the field.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider sends through one mapped HTTP API.

func (*Provider) Adapter

func (p *Provider) Adapter() string

Adapter implements providers.Provider.

func (*Provider) Capabilities

func (p *Provider) Capabilities() providers.Capabilities

Capabilities implements providers.Provider: what the mapping can do.

func (*Provider) Name

func (p *Provider) Name() string

Name is the installed HTTP adapter the provider uses ("" when the mapping was entered for this provider only).

func (*Provider) ParseWebhook

func (p *Provider) ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]providers.Event, error)

ParseWebhook implements providers.Provider: it verifies the request and maps every selected event.

func (*Provider) Preview

func (p *Provider) Preview(msg providers.Message) (Rendered, error)

Preview renders the request for msg without sending it, with secrets masked.

func (*Provider) Send

func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)

Send implements providers.Provider: one request per message.

func (*Provider) Terms

func (p *Provider) Terms() Terms

Terms returns what the mapping's manifest says about the provider's terms.

func (*Provider) VerifyWebhook

func (p *Provider) VerifyWebhook(_ context.Context, r *http.Request, body []byte) error

VerifyWebhook implements providers.WebhookVerifier.

func (*Provider) WebhookSecretHeaders

func (p *Provider) WebhookSecretHeaders() []string

WebhookSecretHeaders implements providers.WebhookSecrets: with auth "header" the secret travels as it is, and its header is never stored with the raw event.

type Rendered

type Rendered struct {
	Method string
	URL    string
	Header http.Header
	Body   string
}

Rendered is a request built from the mapping, for the "Test with a sample message" preview. Secret values are replaced by "••••".

func PreviewManifest

func PreviewManifest(raw []byte) (Rendered, error)

PreviewManifest renders the request an HTTP adapter's manifest would send for the sample message, with every secret shown as "••••" (the Adapters tab's "Test with a sample message").

type Settings

type Settings struct {
	// Adapter names the installed HTTP adapter the mapping came from.
	Adapter string   `json:"adapter,omitempty"`
	HTTP    *Mapping `json:"http"`
	Terms   *Terms   `json:"terms,omitempty"`
	Pricing string   `json:"pricing,omitempty"`
}

Settings are a connected provider's non-secret settings (providers.config). Every other top-level string or number is a connection value the templates read as settings.<key>.

type Terms

type Terms struct {
	Bulk providers.BulkPolicy `json:"bulk"`
	Note string               `json:"note,omitempty"`
	// URL is the provider's acceptable-use policy.
	URL string `json:"url,omitempty"`
}

Terms is what an HTTP adapter's manifest says about the provider's terms.

type WebhookSpec

type WebhookSpec struct {
	// Auth is how a request proves it comes from the provider:
	//   - "hmac" (the default): a signature header, the HMAC of the body
	//     (or of SignedPayload) with the signing secret;
	//   - "standard": Standard Webhooks / Svix (webhook-id,
	//     webhook-timestamp, webhook-signature; a whsec_ secret);
	//   - "basic": HTTP basic auth, user Username and the secret as password;
	//   - "header": the secret itself in TokenHeader;
	//   - "none": nothing but the unguessable webhook URL.
	Auth string `json:"auth,omitempty"`
	// SignatureHeader carries the signature (default X-Signature).
	SignatureHeader string `json:"signature_header,omitempty"`
	// Algorithm is sha256 (default), sha1 or sha512.
	Algorithm string `json:"algorithm,omitempty"`
	// Encoding of the signature: hex (default) or base64.
	Encoding string `json:"encoding,omitempty"`
	// SignaturePrefix is stripped from the header value ("sha256=").
	SignaturePrefix string `json:"signature_prefix,omitempty"`
	// TimestampHeader names a signed timestamp header; requests more than
	// five minutes old are refused as replays.
	TimestampHeader string `json:"timestamp_header,omitempty"`
	// SignedPayload is what is signed, with {timestamp} and {body}
	// standing for the timestamp header and the raw body. Default
	// "{timestamp}.{body}" with a timestamp header, else "{body}".
	SignedPayload string `json:"signed_payload,omitempty"`
	// Secret is a template for the signing secret ("{{ secrets.signing_key }}").
	// Default: the webhook_signing_key credential, else the webhook secret
	// ReputeCast generated for the provider.
	Secret string `json:"secret,omitempty"`
	// TokenHeader carries the secret for auth "header".
	TokenHeader string `json:"token_header,omitempty"`
	// Username is the basic-auth user for auth "basic" (default reputecast).
	Username string `json:"username,omitempty"`

	// EventsPath selects the events in the payload (default "$": the
	// payload is one event, or an array of events).
	EventsPath string `json:"events_path,omitempty"`
	// Paths inside one event. With webhook_mapping "status" they default
	// to $.status, $.recipient, $.message_id, $.reputecast_id, $.code,
	// $.reason, $.timestamp, $.url and $.user_agent.
	TypePath         string `json:"type_path,omitempty"`
	RecipientPath    string `json:"recipient_path,omitempty"`
	MessageIDPath    string `json:"message_id_path,omitempty"`
	ReputeCastIDPath string `json:"reputecast_id_path,omitempty"`
	CodePath         string `json:"code_path,omitempty"`
	DiagnosticPath   string `json:"diagnostic_path,omitempty"`
	TimePath         string `json:"time_path,omitempty"`
	URLPath          string `json:"url_path,omitempty"`
	UserAgentPath    string `json:"user_agent_path,omitempty"`
	// Types maps the provider's event types to ReputeCast's (delivered,
	// deferred, hard_bounce, soft_bounce, bounce, complaint, rejected, open,
	// click, unsubscribe, ignore). Types not listed fall back to the status
	// vocabulary (delivered, bounced, complained…) and are otherwise ignored.
	Types map[string]string `json:"types,omitempty"`
}

WebhookSpec says how a provider's webhook requests are authenticated and how their payload maps to ReputeCast events.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL