feat(experimental): adds transaction started and transaction closed h…

…ooks to the middleware.

This is specially useful when you want to use transaction data to populate things like logs or spans in a trace enriching the experience and connecting the dots with observability.

experimental/plugins/plugintypes/transaction.go

@@ -4,6 +4,8 @@
 package plugintypes
 
 import (
+	"context"
+
 	"github.com/corazawaf/coraza/v3/collection"
 	"github.com/corazawaf/coraza/v3/debuglog"
 	"github.com/corazawaf/coraza/v3/types"
@@ -34,7 +36,11 @@ type TransactionState interface {
 	// CaptureField captures a field.
 	CaptureField(idx int, value string)
 
+	// LastPhase that was evaluated
 	LastPhase() types.RulePhase
+
+	// Context returns the context of the transaction.
+	Context() context.Context
 }
 
 // TransactionVariables has pointers to all the variables of the transaction

http/middleware.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/corazawaf/coraza/v3"
 	"github.com/corazawaf/coraza/v3/experimental"
+	"github.com/corazawaf/coraza/v3/experimental/plugins/plugintypes"
 	"github.com/corazawaf/coraza/v3/types"
 )
 
@@ -113,7 +114,43 @@ func processRequest(tx types.Transaction, req *http.Request) (*types.Interruptio
 	return tx.ProcessRequestBody()
 }
 
+// Options is a set of options for the middleware
+type Options struct {
+	// OnTransactionStarted is called when a new transaction is started. It is useful to
+	// complement observability signals like metrics, traces and logs by providing additional
+	// context about the transaction.
+	OnTransactionStarted func(tx plugintypes.TransactionState)
+
+	// OnTransactionClosed is called when a transaction is closed, after the response has been
+	// written. It is useful to complement observability signals like metrics, traces and logs
+	// by providing additional context about the transaction and the rules that were matched.
+	OnTransactionClosed func(tx plugintypes.TransactionState, matchedRules []types.MatchedRule)
+}
+
+var defaultOptions = Options{
+	OnTransactionStarted: func(plugintypes.TransactionState) {},
+	OnTransactionClosed:  func(plugintypes.TransactionState, []types.MatchedRule) {},
+}
+
+func (o *Options) loadDefaults() {
+	if o.OnTransactionStarted == nil {
+		o.OnTransactionStarted = defaultOptions.OnTransactionStarted
+	}
+	if o.OnTransactionClosed == nil {
+		o.OnTransactionClosed = defaultOptions.OnTransactionClosed
+	}
+}
+
 func WrapHandler(waf coraza.WAF, h http.Handler) http.Handler {
+	return wrapHandler(waf, h, defaultOptions)
+}
+
+func WrapHandlerWithOptions(waf coraza.WAF, h http.Handler, opts Options) http.Handler {
+	opts.loadDefaults()
+	return wrapHandler(waf, h, opts)
+}
+
+func wrapHandler(waf coraza.WAF, h http.Handler, opts Options) http.Handler {
 	if waf == nil {
 		return h
 	}
@@ -132,13 +169,16 @@ func WrapHandler(waf coraza.WAF, h http.Handler) http.Handler {
 
 	fn := func(w http.ResponseWriter, r *http.Request) {
 		tx := newTX(r)
+		txs := tx.(plugintypes.TransactionState)
+		opts.OnTransactionStarted(txs)
 		defer func() {
 			// We run phase 5 rules and create audit logs (if enabled)
 			tx.ProcessLogging()
 			// we remove temporary files and free some memory
 			if err := tx.Close(); err != nil {
 				tx.DebugLogger().Error().Err(err).Msg("Failed to close the transaction")
 			}
+			opts.OnTransactionClosed(txs, tx.MatchedRules())
 		}()
 
 		// Early return, Coraza is not going to process any rule

http/middleware_test.go

@@ -10,6 +10,7 @@ package http
 import (
 	"bufio"
 	"bytes"
+	"context"
 	"fmt"
 	"io"
 	"mime/multipart"
@@ -23,6 +24,7 @@ import (
 	"github.com/corazawaf/coraza/v3"
 	"github.com/corazawaf/coraza/v3/debuglog"
 	"github.com/corazawaf/coraza/v3/experimental/plugins/macro"
+	"github.com/corazawaf/coraza/v3/experimental/plugins/plugintypes"
 	"github.com/corazawaf/coraza/v3/internal/corazawaf"
 	"github.com/corazawaf/coraza/v3/internal/seclang"
 	"github.com/corazawaf/coraza/v3/types"
@@ -213,6 +215,7 @@ func TestChainEvaluation(t *testing.T) {
 }
 
 func errLogger(t *testing.T) func(rule types.MatchedRule) {
+	t.Helper()
 	return func(rule types.MatchedRule) {
 		t.Log(rule.ErrorLog())
 	}
@@ -606,3 +609,23 @@ func TestHandlerAPI(t *testing.T) {
 		})
 	}
 }
+
+type ctxKey struct{}
+
+func TestWrapHandlerWithOptions(t *testing.T) {
+	waf, _ := coraza.NewWAF(coraza.NewWAFConfig())
+	delegateHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})
+
+	ctx := context.WithValue(context.Background(), ctxKey{}, "value")
+	req, _ := http.NewRequestWithContext(ctx, "GET", "https://www.coraza.io/test", nil)
+
+	wrappedHandler := WrapHandlerWithOptions(waf, delegateHandler, Options{
+		OnTransactionStarted: func(tx plugintypes.TransactionState) {
+			if want, have := "value", tx.Context().Value(ctxKey{}).(string); want != have {
+				t.Errorf("unexpected context value, want: %s, have: %s", want, have)
+			}
+		},
+	}).(http.HandlerFunc)
+
+	wrappedHandler(httptest.NewRecorder(), req)
+}

internal/corazawaf/transaction.go

@@ -126,6 +126,10 @@ func (tx *Transaction) ID() string {
 	return tx.id
 }
 
+func (tx *Transaction) Context() context.Context {
+	return tx.context
+}
+
 func (tx *Transaction) Variables() plugintypes.TransactionVariables {
 	return &tx.variables
 }