Merge pull request #22 from nacorid/main

feat: Add before/after verify/settle hooks

Author: nacorid

http/facilitator.go

@@ -25,6 +25,15 @@ import (
 // does not serialize calls to the provider.
 type AuthorizationProvider func(*http.Request) string
 
+// OnBeforeFunc is a function that returns an error to abort an operation.
+type OnBeforeFunc func(context.Context, x402.PaymentPayload, x402.PaymentRequirement) error
+
+// OnAfterVerifyFunc is a function that is called after a Verify operation completes
+type OnAfterVerifyFunc func(context.Context, x402.PaymentPayload, x402.PaymentRequirement, *facilitator.VerifyResponse, error)
+
+// OnAfterSettleFunc is a function that is called after a Settle operation completes
+type OnAfterSettleFunc func(context.Context, x402.PaymentPayload, x402.PaymentRequirement, *x402.SettlementResponse, error)
+
 // FacilitatorClient is a client for communicating with x402 facilitator services.
 type FacilitatorClient struct {
 	BaseURL    string
@@ -41,6 +50,20 @@ type FacilitatorClient struct {
 	// This is useful for dynamic tokens that may need to be refreshed.
 	// If set, this takes precedence over the static Authorization field.
 	AuthorizationProvider AuthorizationProvider
+
+	// OnBeforeVerify is called before the Verify operation starts.
+	// If it returns an error, the operation is aborted immediately.
+	OnBeforeVerify OnBeforeFunc
+
+	// OnAfterVerify is called after the Verify operation completes (success or failure).
+	OnAfterVerify OnAfterVerifyFunc
+
+	// OnBeforeSettle is called before the Settle operation starts.
+	// If it returns an error, the operation is aborted immediately.
+	OnBeforeSettle OnBeforeFunc
+
+	// OnAfterSettle is called after the Settle operation completes (success or failure).
+	OnAfterSettle OnAfterSettleFunc
 }
 
 // setAuthorizationHeader sets the Authorization header on the request if configured.
@@ -67,6 +90,12 @@ type FacilitatorRequest struct {
 
 // Verify verifies a payment authorization without executing the transaction.
 func (c *FacilitatorClient) Verify(ctx context.Context, payment x402.PaymentPayload, requirement x402.PaymentRequirement) (*facilitator.VerifyResponse, error) {
+	if c.OnBeforeVerify != nil {
+		if err := c.OnBeforeVerify(ctx, payment, requirement); err != nil {
+			return nil, err
+		}
+	}
+
 	// Create request payload
 	req := FacilitatorRequest{
 		X402Version:         1,
@@ -98,7 +127,7 @@ func (c *FacilitatorClient) Verify(ctx context.Context, payment x402.PaymentPayl
 		Multiplier:   2.0,
 	}
 
-	return retry.WithRetry(ctx, config, isFacilitatorUnavailableError, func() (*facilitator.VerifyResponse, error) {
+	resp, resultErr := retry.WithRetry(ctx, config, isFacilitatorUnavailableError, func() (*facilitator.VerifyResponse, error) {
 		// Use provided context, apply timeout only if not already set
 		reqCtx := ctx
 		if _, hasDeadline := ctx.Deadline(); !hasDeadline && c.Timeouts.VerifyTimeout > 0 {
@@ -153,6 +182,12 @@ func (c *FacilitatorClient) Verify(ctx context.Context, payment x402.PaymentPayl
 
 		return &verifyResp, nil
 	})
+
+	if c.OnAfterVerify != nil {
+		c.OnAfterVerify(ctx, payment, requirement, resp, resultErr)
+	}
+
+	return resp, resultErr
 }
 
 // Supported queries the facilitator for supported payment types.
@@ -193,6 +228,12 @@ func (c *FacilitatorClient) Supported(ctx context.Context) (*facilitator.Support
 
 // Settle executes a verified payment on the blockchain.
 func (c *FacilitatorClient) Settle(ctx context.Context, payment x402.PaymentPayload, requirement x402.PaymentRequirement) (*x402.SettlementResponse, error) {
+	if c.OnBeforeSettle != nil {
+		if err := c.OnBeforeSettle(ctx, payment, requirement); err != nil {
+			return nil, err
+		}
+	}
+
 	// Create request payload
 	req := FacilitatorRequest{
 		X402Version:         1,
@@ -224,7 +265,7 @@ func (c *FacilitatorClient) Settle(ctx context.Context, payment x402.PaymentPayl
 		Multiplier:   2.0,
 	}
 
-	return retry.WithRetry(ctx, config, isFacilitatorUnavailableError, func() (*x402.SettlementResponse, error) {
+	resp, resultErr := retry.WithRetry(ctx, config, isFacilitatorUnavailableError, func() (*x402.SettlementResponse, error) {
 		// Use provided context, apply timeout only if not already set
 		reqCtx := ctx
 		if _, hasDeadline := ctx.Deadline(); !hasDeadline && c.Timeouts.SettleTimeout > 0 {
@@ -271,6 +312,12 @@ func (c *FacilitatorClient) Settle(ctx context.Context, payment x402.PaymentPayl
 
 		return &settlementResp, nil
 	})
+
+	if c.OnAfterSettle != nil {
+		c.OnAfterSettle(ctx, payment, requirement, resp, resultErr)
+	}
+
+	return resp, resultErr
 }
 
 // EnrichRequirements fetches supported payment types from the facilitator and

http/facilitator_test.go

@@ -234,6 +234,80 @@ func TestFacilitatorClient_Verify_WithoutAuthorization(t *testing.T) {
 	}
 }
 
+func TestFacilitatorClient_Verify_Hooks(t *testing.T) {
+	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		response := facilitator.VerifyResponse{IsValid: true}
+		w.Header().Set("Content-Type", "application/json")
+		if err := json.NewEncoder(w).Encode(response); err != nil {
+			t.Errorf("Failed to encode response: %v", err)
+		}
+	}))
+	defer mockServer.Close()
+
+	var beforeCalled, afterCalled bool
+	var capturedPayload x402.PaymentPayload
+
+	client := &FacilitatorClient{
+		BaseURL:  mockServer.URL,
+		Client:   &http.Client{},
+		Timeouts: x402.DefaultTimeouts,
+		OnBeforeVerify: func(ctx context.Context, p x402.PaymentPayload, r x402.PaymentRequirement) error {
+			beforeCalled = true
+			capturedPayload = p
+			return nil
+		},
+		OnAfterVerify: func(ctx context.Context, p x402.PaymentPayload, r x402.PaymentRequirement, resp *facilitator.VerifyResponse, err error) {
+			afterCalled = true
+			if err != nil {
+				t.Errorf("OnAfterVerify received unexpected error: %v", err)
+			}
+			if resp == nil || !resp.IsValid {
+				t.Error("OnAfterVerify did not receive valid response")
+			}
+		},
+	}
+
+	payload := x402.PaymentPayload{X402Version: 1, Scheme: "exact"}
+	requirement := x402.PaymentRequirement{Scheme: "exact"}
+
+	_, err := client.Verify(context.Background(), payload, requirement)
+	if err != nil {
+		t.Fatalf("Verify failed: %v", err)
+	}
+
+	if !beforeCalled {
+		t.Error("OnBeforeVerify was not called")
+	}
+	if !afterCalled {
+		t.Error("OnAfterVerify was not called")
+	}
+	if capturedPayload.Scheme != "exact" {
+		t.Error("OnBeforeVerify did not receive correct payload")
+	}
+}
+
+func TestFacilitatorClient_Verify_OnBeforeAbort(t *testing.T) {
+	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Error("Server was reached despite OnBeforeVerify error")
+	}))
+	defer mockServer.Close()
+
+	expectedErr := x402.ErrVerificationFailed
+
+	client := &FacilitatorClient{
+		BaseURL: mockServer.URL,
+		Client:  &http.Client{},
+		OnBeforeVerify: func(ctx context.Context, pp x402.PaymentPayload, pr x402.PaymentRequirement) error {
+			return expectedErr
+		},
+	}
+
+	_, err := client.Verify(context.Background(), x402.PaymentPayload{}, x402.PaymentRequirement{})
+	if err != expectedErr {
+		t.Errorf("Expected error %v, got %v", expectedErr, err)
+	}
+}
+
 func TestFacilitatorClient_Settle_WithStaticAuthorization(t *testing.T) {
 	expectedAuth := "Bearer settle-api-key"
 
@@ -396,3 +470,66 @@ func TestFacilitatorClient_Settle(t *testing.T) {
 		t.Error("Expected transaction hash")
 	}
 }
+
+func TestFacilitatorClient_Settle_Hooks(t *testing.T) {
+	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		response := x402.SettlementResponse{Success: true, Transaction: "0x123"}
+		w.Header().Set("Content-Type", "application/json")
+		if err := json.NewEncoder(w).Encode(response); err != nil {
+			t.Errorf("Failed to encode response: %v", err)
+		}
+	}))
+	defer mockServer.Close()
+
+	var beforeCalled, afterCalled bool
+
+	client := &FacilitatorClient{
+		BaseURL:  mockServer.URL,
+		Client:   &http.Client{},
+		Timeouts: x402.DefaultTimeouts,
+		OnBeforeSettle: func(ctx context.Context, p x402.PaymentPayload, r x402.PaymentRequirement) error {
+			beforeCalled = true
+			return nil
+		},
+		OnAfterSettle: func(ctx context.Context, p x402.PaymentPayload, r x402.PaymentRequirement, resp *x402.SettlementResponse, err error) {
+			afterCalled = true
+			if resp == nil || resp.Transaction != "0x123" {
+				t.Error("OnAfterSettle did not receive correct response")
+			}
+		},
+	}
+
+	_, err := client.Settle(context.Background(), x402.PaymentPayload{}, x402.PaymentRequirement{})
+	if err != nil {
+		t.Fatalf("Settle failed: %v", err)
+	}
+
+	if !beforeCalled {
+		t.Error("OnBeforeSettle was not called")
+	}
+	if !afterCalled {
+		t.Error("OnAfterSettle was not called")
+	}
+}
+
+func TestFacilitatorClient_Settle_OnBeforeAbort(t *testing.T) {
+	mockServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Error("Server was reached despite OnBeforeSettle error")
+	}))
+	defer mockServer.Close()
+
+	expectedErr := x402.ErrSettlementFailed
+
+	client := &FacilitatorClient{
+		BaseURL: mockServer.URL,
+		Client:  &http.Client{},
+		OnBeforeSettle: func(ctx context.Context, p x402.PaymentPayload, r x402.PaymentRequirement) error {
+			return expectedErr
+		},
+	}
+
+	_, err := client.Settle(context.Background(), x402.PaymentPayload{}, x402.PaymentRequirement{})
+	if err != expectedErr {
+		t.Errorf("Expected error %v, got %v", expectedErr, err)
+	}
+}

http/middleware.go

@@ -32,12 +32,24 @@ type Config struct {
 	// If set, this takes precedence over FacilitatorAuthorization.
 	FacilitatorAuthorizationProvider AuthorizationProvider
 
+	// Facilitator hooks for custom logic before/after verify and settle operations
+	FacilitatorOnBeforeVerify OnBeforeFunc
+	FacilitatorOnAfterVerify  OnAfterVerifyFunc
+	FacilitatorOnBeforeSettle OnBeforeFunc
+	FacilitatorOnAfterSettle  OnAfterSettleFunc
+
 	// FallbackFacilitatorAuthorization is a static Authorization header value for the fallback facilitator.
 	FallbackFacilitatorAuthorization string
 
 	// FallbackFacilitatorAuthorizationProvider is a function that returns an Authorization header value
 	// for the fallback facilitator. If set, this takes precedence over FallbackFacilitatorAuthorization.
 	FallbackFacilitatorAuthorizationProvider AuthorizationProvider
+
+	// FallbackFacilitator hooks for custom logic before/after verify and settle operations
+	FallbackFacilitatorOnBeforeVerify OnBeforeFunc
+	FallbackFacilitatorOnAfterVerify  OnAfterVerifyFunc
+	FallbackFacilitatorOnBeforeSettle OnBeforeFunc
+	FallbackFacilitatorOnAfterSettle  OnAfterSettleFunc
 }
 
 // contextKey is a custom type for context keys to avoid collisions.
@@ -58,6 +70,10 @@ func NewX402Middleware(config *Config) func(http.Handler) http.Handler {
 		Timeouts:              x402.DefaultTimeouts,
 		Authorization:         config.FacilitatorAuthorization,
 		AuthorizationProvider: config.FacilitatorAuthorizationProvider,
+		OnBeforeVerify:        config.FacilitatorOnBeforeVerify,
+		OnAfterVerify:         config.FacilitatorOnAfterVerify,
+		OnBeforeSettle:        config.FacilitatorOnBeforeSettle,
+		OnAfterSettle:         config.FacilitatorOnAfterSettle,
 	}
 
 	// Create fallback facilitator client if configured
@@ -69,6 +85,10 @@ func NewX402Middleware(config *Config) func(http.Handler) http.Handler {
 			Timeouts:              x402.DefaultTimeouts,
 			Authorization:         config.FallbackFacilitatorAuthorization,
 			AuthorizationProvider: config.FallbackFacilitatorAuthorizationProvider,
+			OnBeforeVerify:        config.FallbackFacilitatorOnBeforeVerify,
+			OnAfterVerify:         config.FallbackFacilitatorOnAfterVerify,
+			OnBeforeSettle:        config.FallbackFacilitatorOnBeforeSettle,
+			OnAfterSettle:         config.FallbackFacilitatorOnAfterSettle,
 		}
 	}