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
- func CommunityDescriptor(key, name, version, maintainer string, raw []byte) (providers.Descriptor, error)
- func Descriptor() providers.Descriptor
- func FromManifest(raw []byte, cfg providers.Config) (providers.Provider, error)
- func New(cfg providers.Config) (providers.Provider, error)
- func SampleMessage() providers.Message
- type CheckSpec
- type Checked
- type FieldError
- type Manifest
- type Mapping
- type Provider
- func (p *Provider) Adapter() string
- func (p *Provider) Capabilities() providers.Capabilities
- func (p *Provider) Name() string
- func (p *Provider) ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]providers.Event, error)
- func (p *Provider) Preview(msg providers.Message) (Rendered, error)
- func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)
- func (p *Provider) Terms() Terms
- func (p *Provider) VerifyWebhook(_ context.Context, r *http.Request, body []byte) error
- func (p *Provider) WebhookSecretHeaders() []string
- type Rendered
- type Settings
- type Terms
- type WebhookSpec
Constants ¶
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 ¶
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 ¶
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.
type FieldError ¶
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 ¶
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.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider sends through one mapped HTTP API.
func (*Provider) Capabilities ¶
func (p *Provider) Capabilities() providers.Capabilities
Capabilities implements providers.Provider: what the mapping can do.
func (*Provider) Name ¶
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 ¶
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) VerifyWebhook ¶
VerifyWebhook implements providers.WebhookVerifier.
func (*Provider) WebhookSecretHeaders ¶
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 ¶
Rendered is a request built from the mapping, for the "Test with a sample message" preview. Secret values are replaced by "••••".
func PreviewManifest ¶
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.