moonhook
A lightweight MoonBit WebHook processing framework for event driven automation.
webhook
moonbit
event
automation
Author
Version
0.2.0
License
Apache-2.0
Repository
Last updated
15 hours ago
Downloads
3
Dependencies
- moonbitlang/x0.4.46
#zzy12346/moonhook
HookContext
pub(all) struct HookContext {
provider : HookProvider
delivery_id : String
middleware_index : Int
} derive(Eq, Debug)Context supplied to every middleware and terminal handler.
HookDiagnostic
pub(all) struct HookDiagnostic {
provider : String
event_type : String
delivery_id : String
route_name : String
status : HookStatus
verification : VerificationStatus
retry_delay_ms : Int
notes : Array[String]
} derive(Eq, Debug)Human-readable delivery diagnostic report.
HookDiagnostic::HookDiagnostic
fn HookDiagnostic::HookDiagnostic(event : HookEvent, route_name : StringView, result : HookResult, verification : VerificationResult, retry_delay_ms? : Int, notes? : ArrayView[String]) -> HookDiagnosticCreate a diagnostic report from common framework artifacts.
HookDiagnostic::notes_text
Render notes as a semicolon-separated suffix.
HookDiagnostic::summary
Render a compact one-line report.
HookEvent
pub(all) struct HookEvent {
provider : HookProvider
event_type : String
delivery_id : String
idempotency_key : String
body : String
attributes : Map[String, String]
} derive(Eq, Debug)A normalized event after provider-specific parsing.
HookEvent::attribute
Read an optional parsed attribute.
HookEvent::is_from
Check whether the event matches the given provider.
HookEvent::is_type
Check whether the event has a specific normalized type.
HookEvent::with_attribute
Attach a single parsed attribute to an event.
HookMiddleware
Named middleware entry used by the processing pipeline.
HookMiddleware::HookMiddleware
fn HookMiddleware::HookMiddleware(name : StringView, callback : (HookEvent, HookContext) -> MiddlewareOutcome) -> HookMiddlewareHookPipeline
pub struct HookPipeline {
middlewares : Array[HookMiddleware]
handler : (HookEvent, HookContext) -> HookResult
}Ordered middleware pipeline with a terminal event handler.
HookPipeline::run
Execute middleware in order and invoke the handler only when none halts.
HookPipeline::use_middleware
fn HookPipeline::use_middleware(self : HookPipeline, name : StringView, callback : (HookEvent, HookContext) -> MiddlewareOutcome) -> HookPipelineAppend middleware while preserving registration order.
HookProvider
Built-in provider families supported by MoonHook adapters.
HookProvider::slug
Return a stable provider slug for logs, ids, and JSON fields.
HookRequest
pub(all) struct HookRequest {
provider : HookProvider
event_type : String
delivery_id : String
timestamp : String?
headers : Map[String, String]
body : String
} derive(Eq, Debug)A normalized incoming WebHook request.
HookRequest::HookRequest
fn HookRequest::HookRequest(provider : HookProvider, event_type : StringView, delivery_id : StringView, body : StringView, timestamp? : StringView, headers? : Map[String, String]) -> HookRequestCreate a request with normalized names used by all adapters.
HookRequest::has_event_type
Check whether the request carries an event type.
HookRequest::header
Return a header by normalized, case-insensitive key.
HookRequest::is_from
Check whether the request comes from a provider.
HookRequest::to_event
Convert a raw request into the minimal normalized event.
HookResult
pub(all) struct HookResult {
status : HookStatus
message : String
retryable : Bool
attempts : Int
} derive(Eq, Debug)A structured result that can be logged, retried, or asserted in tests.
HookResult::HookResult
fn HookResult::HookResult(status : HookStatus, message : StringView, retryable? : Bool, attempts? : Int) -> HookResultConstruct a general result.
HookResult::is_ok
Whether the final state represents successful completion.
HookResult::should_retry
Whether another delivery attempt should be scheduled.
HookRoute
A declarative WebHook route.
HookRoute::HookRoute
Build a route for all providers and all event types.
HookRouter
A router is intentionally declarative so tests and CLIs can inspect it.
HookRouter::add
Register a route and return the updated router.
HookRouter::dispatch
Dispatch returns an accepted result for a matched route and fallback otherwise.
HookRouter::enabled_count
Count enabled routes for diagnostics.
HookRouter::match_event
Resolve the first matching route.
HookRouter::on
fn HookRouter::on(self : HookRouter, provider : HookProvider, event_type : StringView, name? : StringView) -> HookRouterRegister an exact provider/event route.
HookRouter::on_event
fn HookRouter::on_event(self : HookRouter, event_type : StringView, name? : StringView) -> HookRouterRegister an event-type-only route.
HookRouter::on_provider
fn HookRouter::on_provider(self : HookRouter, provider : HookProvider, name? : StringView) -> HookRouterRegister a provider-only route.
HookRouter::with_fallback
Replace the router fallback result.
HookStatus
User-facing processing status returned by handlers and middleware.
HookStatus::to_string
Stable text used by diagnostics and examples.
HttpParseResult
HttpRequest
Transport-neutral HTTP request parsed from a server or test fixture.
HttpResponse
HTTP response returned by a WebHook endpoint.
HttpResponse::HttpResponse
HttpResponse::render
Serialize a response for a TCP/HTTP server binding.
IdempotencyRecord
pub(all) struct IdempotencyRecord {
key : String
status : HookStatus
note : String
first_seen_at : String
expires_at : String
} derive(Eq, Debug)Stored idempotency decision.
IdempotencyRecord::IdempotencyRecord
fn IdempotencyRecord::IdempotencyRecord(key : StringView, status : HookStatus, note : StringView, first_seen_at? : StringView, expires_at? : StringView) -> IdempotencyRecordCreate an idempotency record.
InMemoryDeduper
In-memory idempotency store for tests, examples, and single-process tools.
InMemoryDeduper::contains
Check if an idempotency key already exists.
InMemoryDeduper::get
Read a record by key.
InMemoryDeduper::guard_event
Return accepted when the event is new and ignored when duplicate.
InMemoryDeduper::put
Store a record and return the updated deduper.
InMemoryDeduper::remember_event
fn InMemoryDeduper::remember_event(self : InMemoryDeduper, event : HookEvent, now : StringView) -> InMemoryDeduperStore an accepted event.
InMemoryDeduper::should_process
Determine whether an event should be processed.
MatchMode
Matching mode for a route condition.
MiddlewareOutcome
Middleware either forwards an enriched event or stops processing.
PayloadDocument
Result of parsing a WebHook JSON payload.
PipelineResult
pub(all) struct PipelineResult {
event : HookEvent
result : HookResult
executed : Array[String]
} derive(Debug)Execution details exposed to HTTP adapters, logs, and tests.
ProviderAdapter
pub(all) struct ProviderAdapter {
provider : HookProvider
event_header : String
delivery_header : String
signature_header : String?
} derive(Eq, Debug)Normalized provider adapter metadata.
ProviderAdapter::ProviderAdapter
fn ProviderAdapter::ProviderAdapter(provider : HookProvider, event_header : StringView, delivery_header : StringView, signature_header? : StringView) -> ProviderAdapterConstruct adapter metadata.
ProviderAdapter::parse_event
fn ProviderAdapter::parse_event(self : ProviderAdapter, headers : Map[String, String], body : StringView) -> HookEventParse provider headers and a JSON body into a normalized, enriched event.
ProviderAdapter::parse_request
fn ProviderAdapter::parse_request(self : ProviderAdapter, headers : Map[String, String], body : StringView) -> HookRequestConvert provider headers and body into a normalized request.
ProviderAdapter::verify_presence
fn ProviderAdapter::verify_presence(self : ProviderAdapter, request : HookRequest) -> VerificationResultVerify the configured signature header is present when the adapter has one.
ProviderCapability
pub(all) struct ProviderCapability {
provider : HookProvider
supports_signature : Bool
supports_delivery_id : Bool
supports_retry : Bool
common_events : Array[String]
} derive(Eq, Debug)Static provider capability description.
ProviderCapability::ProviderCapability
fn ProviderCapability::ProviderCapability(provider : HookProvider, supports_signature? : Bool, supports_delivery_id? : Bool, supports_retry? : Bool, common_events? : ArrayView[String]) -> ProviderCapabilityConstruct a provider capability profile.
RetryBackoff
Retry delay strategy.
RetryPolicy
pub(all) struct RetryPolicy {
max_attempts : Int
base_delay_ms : Int
max_delay_ms : Int
jitter_ms : Int
backoff : RetryBackoff
} derive(Eq, Debug)Declarative retry policy for failed WebHook processing.
RetryPolicy::RetryPolicy
fn RetryPolicy::RetryPolicy(max_attempts? : Int, base_delay_ms? : Int, max_delay_ms? : Int, jitter_ms? : Int, backoff? : RetryBackoff) -> RetryPolicyCreate a retry policy.
RetryPolicy::can_retry
Decide whether a result should be attempted again.
RetryPolicy::delay_for_attempt
Compute delay for a 1-based attempt number.
RetryPolicy::schedule
Convert a failed result into a scheduled retry when policy allows it.
SignatureVerifier
Signature verifier configuration.
SignatureVerifier::SignatureVerifier
fn SignatureVerifier::SignatureVerifier(algorithm : StringView, header_name : StringView, secret_hint : StringView) -> SignatureVerifierConstruct a verifier descriptor.
SignatureVerifier::verify_hmac_sha256
fn SignatureVerifier::verify_hmac_sha256(self : SignatureVerifier, request : HookRequest, secret : String) -> VerificationResultVerify an HMAC-SHA256 signature against the unmodified request body.
The comparison is constant-time and accepts the conventional sha256= prefix.
SignatureVerifier::verify_presence
fn SignatureVerifier::verify_presence(self : SignatureVerifier, request : HookRequest) -> VerificationResultCheck whether the required signature header exists.
VerificationResult
Details returned by a verifier.
VerificationResult::VerificationResult
fn VerificationResult::VerificationResult(status : VerificationStatus, reason : StringView) -> VerificationResultConstruct a verification result.
VerificationStatus
Verification outcome for request signatures and timestamp checks.
VerificationStatus::to_string
Stable text used by diagnostics and examples.
WebhookEndpoint
pub struct WebhookEndpoint {
path : String
adapter : ProviderAdapter
secret : String
router : HookRouter
middlewares : Array[HookMiddleware]
deduper : InMemoryDeduper
max_body_bytes : Int
}Stateful endpoint joining HTTP parsing, HMAC verification, JSON parsing,
middleware, deduplication, and routing.
WebhookEndpoint::handle_http
fn WebhookEndpoint::handle_http(self : WebhookEndpoint, http : HttpRequest) -> (WebhookEndpoint, HttpResponse)Handle a structured HTTP request supplied by any MoonBit server runtime.
Signature verification happens before payload parsing and routing.
WebhookEndpoint::handle_raw
fn WebhookEndpoint::handle_raw(self : WebhookEndpoint, raw : String) -> (WebhookEndpoint, HttpResponse)Parse and handle one raw HTTP/1.x request.
WebhookEndpoint::use_middleware
fn WebhookEndpoint::use_middleware(self : WebhookEndpoint, name : StringView, callback : (HookEvent, HookContext) -> MiddlewareOutcome) -> WebhookEndpointWebhookEndpoint::with_max_body_bytes
fn WebhookEndpoint::with_max_body_bytes(self : WebhookEndpoint, max_body_bytes : Int) -> WebhookEndpointall_generated_fixtures
Return all generated fixtures. This is intentionally explicit so coverage
tools and docs can point to stable function names.
attribute_middleware
fn attribute_middleware(key : String, value : String) -> ((HookEvent, HookContext) -> MiddlewareOutcome)Built-in middleware that enriches every event with a static attribute.
builtin_capabilities
All built-in provider capability profiles.
constant_time_equal
fn constant_time_equal(left : String, right : String) -> BoolCompare signatures without returning early on the first different byte.
Length is folded into the accumulated difference to avoid prefix matches.
enrich_provider_event
Enrich a normalized event with real provider payload metadata.
exponential_retry_policy
fn exponential_retry_policy(attempts? : Int, base_delay_ms? : Int, max_delay_ms? : Int) -> RetryPolicyRetry with an exponential delay.
find_capability
Find a capability by provider.
fixed_retry_policy
Retry with a fixed delay.
github_sha256_verifier
Standard GitHub HMAC-SHA256 verifier descriptor.
gitlab_token_verifier
Standard GitLab token verifier descriptor.
header_value
Read a header from a raw map using HTTP's case-insensitive name rules.
hmac_sha256_hex
fn hmac_sha256_hex(secret : String, message : String) -> StringReturn the lowercase HMAC-SHA256 digest of a UTF-8 payload.
json_path
Return a nested JSON value using object-key path segments.
make_idempotency_key
Build the default idempotency key from provider and delivery id.
new_github_endpoint
Create a GitHub-compatible HMAC-SHA256 WebHook endpoint.
new_hook_pipeline
new_in_memory_deduper
Create an empty in-memory store.
parse_http_request
Parse an HTTP/1.x request and normalize header names to lowercase.
parse_payload
Parse JSON while preserving invalid input as a diagnostic value.
payload_path
Read a nested JSON value as text.
report_matched_delivery
fn report_matched_delivery(event : HookEvent, route : HookRoute, verification : VerificationResult) -> HookDiagnosticBuild a report for a matched route.
report_unmatched_delivery
fn report_unmatched_delivery(event : HookEvent, verification : VerificationResult) -> HookDiagnosticBuild a report for an unmatched delivery.
representative_fixtures
Return one representative fixture for each built-in provider.
require_attribute_middleware
Built-in middleware that rejects events missing a parsed attribute.
require_json_middleware
Built-in middleware that requires valid JSON before routing.
sha256_hex
fn sha256_hex(message : String) -> StringReturn the lowercase SHA-256 digest of a UTF-8 string.
sign_github_body
fn sign_github_body(secret : String, body : String) -> StringBuild the GitHub-compatible signature header value for an exact raw body.
stripe_signature_verifier
Standard Stripe signature verifier descriptor.
verify_github_signature
Verify a GitHub X-Hub-Signature-256 header using the exact raw body.
Install
Download zipA lightweight MoonBit WebHook processing framework for event driven automation.
webhookmoonbiteventautomation
0.2.0
Apache-2.0
Updated 15 hours ago
3 downloadsDependencies
- moonbitlang/x0.4.46