Public API: Load() (#17)

- `func Load() (ok bool, err error)` to ease the integration in
dd-trace-go so that we can distinguish the different possible error
cases:
- Panic errors that must be used to gracefully abort the caller and
prevent it from continuing. Such errors are represented by the new
`PanicError` error type.
- Unsupported target OS and/or architecture, which must be handled as an
informative error, is worth logging to the user, and prevents the caller
from continuing. This error is represented by the new
`UnsupportedTarget` error type.
- Every other unexpected error that can possible happen is returned
as-is, but `ok` is `false`, so that the caller knows it cannot use the
package.
- Informative errors, about internal non-critical failures, can also
happen (eg. if os.Remove fails removing the temporary files), and are
returned as-is, but with `ok` being `true` so that the caller can log
the error and continue its startup.
- The dd-trace-go integration of this PR can be found here
DataDog/dd-trace-go#2090
- Note that `Health()` has been kept for the sake of simplicity
health-checking cases such as in the tests, where it returns the
`Load()` error only if `ok` is false, meaning that go-libddwaf is not
healthy.
- Simplified build tags, removed everywhere it was possible, down to
purego which isn't properly stubbed for unsupported targets and which we
stub ourselves at our level in the new `waf_dl_unsupported.go` file.

---------

Co-authored-by: Eliott Bouhana <[email protected]>
Co-authored-by: François Mazeau <[email protected]>

Author: 3 people

cgo_ref_pool.go

@@ -3,8 +3,6 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
-//go:build (linux || darwin) && (amd64 || arm64)
-
 package waf
 
 import (

context.go

@@ -3,8 +3,6 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
-//go:build (linux || darwin) && (amd64 || arm64)
-
 package waf
 
 import (
@@ -56,7 +54,6 @@ func NewContext(handle *Handle) *Context {
 	return &Context{handle: handle, cContext: cContext}
 }
 
-
 // Run encodes the given addressesToData values and runs them against the WAF rules within the given
 // timeout value. It returns the matches as a JSON string (usually opaquely used) along with the corresponding
 // actions in any. In case of an error, matches and actions can still be returned, for instance in the case of a

ctypes.go

@@ -3,9 +3,6 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
-// Purego only works on linux/macOS with amd64 and arm64 for now
-//go:build (linux || darwin) && (amd64 || arm64)
-
 package waf
 
 import (
@@ -162,7 +159,7 @@ func stringToUintptr(arg string) uintptr {
 // keepAlive() globals
 var (
 	alwaysFalse bool
-	escapeSink any
+	escapeSink  any
 )
 
 // keepAlive is a copy of runtime.KeepAlive

ctypes_test.go

@@ -39,7 +39,6 @@ func getSymbol(t *testing.T, lib uintptr, symbol string) uintptr {
 }
 
 func TestWafObject(t *testing.T) {
-
 	lib := getLibddwaf(t)
 
 	t.Run("invalid", func(t *testing.T) {

decoder.go

@@ -3,11 +3,9 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
-//go:build (linux || darwin) && (amd64 || arm64)
-
 package waf
 
-// decodeErrors tranforms the wafObject received by the wafRulesetInfo after the call to wafDl.wafInit to a map where
+// decodeErrors transforms the wafObject received by the wafRulesetInfo after the call to wafDl.wafInit to a map where
 // keys are the error message and the value is a array of all the rule ids which triggered this specific error
 func decodeErrors(obj *wafObject) (map[string][]string, error) {
 	if obj._type != wafMapType {

encoder.go

@@ -3,8 +3,6 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
-//go:build (linux || darwin) && (amd64 || arm64)
-
 package waf
 
 import (

go.mod

@@ -4,6 +4,7 @@ go 1.18
 
 require (
 	github.com/ebitengine/purego v0.4.0-alpha.4.0.20230519103000-ee8dcecc618f
+	github.com/pkg/errors v0.9.1
 	github.com/stretchr/testify v1.8.1
 	go.uber.org/atomic v1.10.0
 )

go.sum

@@ -10,6 +10,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=

handle.go

@@ -3,16 +3,15 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
-//go:build (linux || darwin) && (amd64 || arm64)
-
 package waf
 
 import (
 	"errors"
 	"fmt"
+	"sync"
+
 	"github.com/DataDog/go-libddwaf/internal/noopfree"
 	"go.uber.org/atomic"
-	"sync"
 )
 
 // Handle represents an instance of the WAF for a given ruleset.
@@ -42,16 +41,20 @@ type Handle struct {
 
 // NewHandle creates and returns a new instance of the WAF with the given security rules and configuration
 // of the sensitive data obfuscator. The returned handle is nil in case of an error.
-// Rules-related metrics, including errors, are accessible with the `RulesetInfo()` method. 
+// Rules-related metrics, including errors, are accessible with the `RulesetInfo()` method.
 func NewHandle(rules any, keyObfuscatorRegex string, valueObfuscatorRegex string) (*Handle, error) {
-// The order of action is the following:
-// - Open the ddwaf C library
-// - Encode the security rules as a ddwaf_object
-// - Create a ddwaf_config object and fill the values
-// - Run ddwaf_init to create a new handle based on the given rules and config
-// - Check for errors and streamline the ddwaf_ruleset_info returned
-	if err := InitWaf(); err != nil {
+	// The order of action is the following:
+	// - Open the ddwaf C library
+	// - Encode the security rules as a ddwaf_object
+	// - Create a ddwaf_config object and fill the values
+	// - Run ddwaf_init to create a new handle based on the given rules and config
+	// - Check for errors and streamline the ddwaf_ruleset_info returned
+
+	if ok, err := Load(); !ok {
 		return nil, err
+		// The case where ok == true && err != nil is ignored on purpose, as
+		// this is out of the scope of NewHandle which only requires a properly
+		// loaded libddwaf in order to use it
 	}
 
 	encoder := newMaxEncoder()
@@ -66,7 +69,7 @@ func NewHandle(rules any, keyObfuscatorRegex string, valueObfuscatorRegex string
 	cHandle := wafLib.wafInit(obj, config, cRulesetInfo)
 	keepAlive(encoder.cgoRefs)
 	// Note that the encoded obj was copied by libddwaf, so we don't need to keep them alive
-	// for the lifetime of the handle (ddwaf API guarantee). 
+	// for the lifetime of the handle (ddwaf API guarantee).
 	if cHandle == 0 {
 		return nil, errors.New("could not instantiate the WAF")
 	}
@@ -111,7 +114,7 @@ func (handle *Handle) closeContext(context *Context) {
 // Close puts the handle in termination state, when all the contexts are closed the handle will be destroyed
 func (handle *Handle) Close() {
 	if handle.addRefCounter(-1) > 0 {
-	// There are still Contexts that are not closed
+		// There are still Contexts that are not closed
 		return
 	}
 

internal/noopfree/noopfree.go

@@ -3,6 +3,9 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2016-present Datadog, Inc.
 
+// Package noopfree provides a noop-ed free function. A separate package is
+// needed to avoid the special go-build case with CGO enabled where it compiles
+// .s files with CC instead of the Go assembler that we want here.
 package noopfree
 
 import "unsafe"