headers: fail Build on missing native exports and assert MI/COM layouts (#2739)

Signed-off-by: Jan-Otto Kröpke <mail@jkroepke.de>

internal/headers/lazyproc/bindings_test.go

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build windows
+
+package lazyproc_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/prometheus-community/windows_exporter/internal/headers/cfgmgr32"
+	"github.com/prometheus-community/windows_exporter/internal/headers/dhcpsapi"
+	"github.com/prometheus-community/windows_exporter/internal/headers/gdi32"
+	"github.com/prometheus-community/windows_exporter/internal/headers/hcn"
+	"github.com/prometheus-community/windows_exporter/internal/headers/hcs"
+	"github.com/prometheus-community/windows_exporter/internal/headers/iphlpapi"
+	"github.com/prometheus-community/windows_exporter/internal/headers/kernel32"
+	"github.com/prometheus-community/windows_exporter/internal/headers/ntdll"
+	"github.com/prometheus-community/windows_exporter/internal/headers/psapi"
+	"github.com/prometheus-community/windows_exporter/internal/headers/slc"
+	"github.com/prometheus-community/windows_exporter/internal/headers/sysinfoapi"
+	"github.com/prometheus-community/windows_exporter/internal/headers/winspool"
+	"github.com/prometheus-community/windows_exporter/internal/headers/wtsapi32"
+	"github.com/prometheus-community/windows_exporter/internal/pdh"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/windows"
+)
+
+// TestBindingsLoad checks the export names of every binding package against
+// the DLLs of this host. A DLL that belongs to an optional Windows feature
+// skips its binding when the DLL is not installed.
+func TestBindingsLoad(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		load func() error
+		// optionalDLL is set for DLLs of optional Windows features.
+		optionalDLL string
+	}{
+		{name: "cfgmgr32", load: cfgmgr32.Load},
+		{name: "dhcpsapi", load: dhcpsapi.Load, optionalDLL: "dhcpsapi.dll"},
+		{name: "gdi32", load: gdi32.Load},
+		{name: "hcn", load: hcn.Load, optionalDLL: "vmcompute.dll"},
+		{name: "hcs", load: hcs.Load, optionalDLL: "computecore.dll"},
+		{name: "iphlpapi", load: iphlpapi.Load},
+		{name: "kernel32", load: kernel32.Load},
+		{name: "ntdll", load: ntdll.Load},
+		{name: "psapi", load: psapi.Load},
+		{name: "slc", load: slc.Load},
+		{name: "sysinfoapi", load: sysinfoapi.Load},
+		{name: "winspool", load: winspool.Load},
+		{name: "wtsapi32", load: wtsapi32.Load},
+		{name: "pdh", load: pdh.Load},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			if tc.optionalDLL != "" {
+				systemDirectory, err := windows.GetSystemDirectory()
+				require.NoError(t, err)
+
+				if _, err := os.Stat(filepath.Join(systemDirectory, tc.optionalDLL)); err != nil {
+					t.Skipf("%s is not installed: %v", tc.optionalDLL, err)
+				}
+			}
+
+			require.NoError(t, tc.load())
+		})
+	}
+}

internal/headers/lazyproc/lazyproc.go

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build windows
+
+// Package lazyproc checks that lazily loaded native functions exist.
+//
+// windows.LazyProc.Call panics when its DLL or export is missing, e.g. on a
+// Windows version or edition without the subsystem. A binding package lists
+// the functions it calls without a check of its own in a Load function built
+// with [Once], and collectors call it in Build, so a missing export fails
+// Build instead of panicking on the first scrape.
+package lazyproc
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+
+	"golang.org/x/sys/windows"
+)
+
+// Error reports a missing DLL or missing exports. It matches
+// [errors.ErrUnsupported] and has no other cause, so a collector that fails
+// Build with it is skipped as an unavailable subsystem: the loader errors,
+// e.g. ERROR_MOD_NOT_FOUND, are only kept as text and in Missing.
+type Error struct {
+	// DLL is the name of the DLL.
+	DLL string
+	// Missing holds the error of the DLL, if it could not be loaded, or of
+	// each missing export.
+	Missing []error
+}
+
+func (e *Error) Error() string {
+	var message strings.Builder
+
+	fmt.Fprintf(&message, "%s: %s", errors.ErrUnsupported, e.DLL)
+
+	for _, err := range e.Missing {
+		message.WriteString(": ")
+		message.WriteString(err.Error())
+	}
+
+	return message.String()
+}
+
+// Is reports whether target is [errors.ErrUnsupported].
+func (e *Error) Is(target error) bool {
+	return target == errors.ErrUnsupported
+}
+
+// Find loads dll and every proc, which must belong to dll. It returns nil if
+// all of them exist, and otherwise an [*Error] that names the missing DLL or
+// each missing export.
+func Find(dll *windows.LazyDLL, procs ...*windows.LazyProc) error {
+	if err := dll.Load(); err != nil {
+		return &Error{DLL: dll.Name, Missing: []error{err}}
+	}
+
+	var missing []error
+
+	for _, proc := range procs {
+		if err := proc.Find(); err != nil {
+			missing = append(missing, err)
+		}
+	}
+
+	if len(missing) == 0 {
+		return nil
+	}
+
+	return &Error{DLL: dll.Name, Missing: missing}
+}
+
+// Once returns a function that runs [Find] once and then returns its result.
+// A DLL or export that is missing stays missing for the life of the process.
+func Once(dll *windows.LazyDLL, procs ...*windows.LazyProc) func() error {
+	return sync.OnceValue(func() error {
+		return Find(dll, procs...)
+	})
+}

internal/headers/lazyproc/lazyproc_test.go

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build windows
+
+package lazyproc_test
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/prometheus-community/windows_exporter/internal/headers/lazyproc"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/windows"
+)
+
+func TestFind(t *testing.T) {
+	t.Parallel()
+
+	kernel32 := windows.NewLazySystemDLL("kernel32.dll")
+	missingDLL := windows.NewLazySystemDLL("windows_exporter_missing.dll")
+
+	t.Run("all present", func(t *testing.T) {
+		t.Parallel()
+
+		require.NoError(t, lazyproc.Find(kernel32, kernel32.NewProc("GetTickCount64"), kernel32.NewProc("GetSystemInfo")))
+		require.NoError(t, lazyproc.Find(kernel32))
+	})
+
+	t.Run("missing export", func(t *testing.T) {
+		t.Parallel()
+
+		err := lazyproc.Find(kernel32, kernel32.NewProc("GetTickCount64"), kernel32.NewProc("WindowsExporterMissingExport"))
+		require.ErrorIs(t, err, errors.ErrUnsupported)
+		require.ErrorContains(t, err, "WindowsExporterMissingExport")
+	})
+
+	t.Run("missing DLL is reported once", func(t *testing.T) {
+		t.Parallel()
+
+		err := lazyproc.Find(missingDLL, missingDLL.NewProc("A"), missingDLL.NewProc("B"))
+		require.ErrorIs(t, err, errors.ErrUnsupported)
+		require.Equal(t, 1, strings.Count(err.Error(), "windows_exporter_missing.dll"), err.Error())
+
+		// The loader error stays text only, so the error has a single cause.
+		require.NotErrorIs(t, err, windows.ERROR_MOD_NOT_FOUND)
+
+		var lazyErr *lazyproc.Error
+
+		require.ErrorAs(t, err, &lazyErr)
+		require.Equal(t, "windows_exporter_missing.dll", lazyErr.DLL)
+		require.Len(t, lazyErr.Missing, 1)
+	})
+
+	t.Run("Once", func(t *testing.T) {
+		t.Parallel()
+
+		load := lazyproc.Once(kernel32, kernel32.NewProc("WindowsExporterMissingExport"))
+
+		first := load()
+		require.ErrorIs(t, first, errors.ErrUnsupported)
+		// The cached error is returned again.
+		require.Same(t, first, load())
+	})
+}