refactor: update interfaces to use any, improve error handling, and enhance documentation

- Refactored all interfaces and implementations to use `any` instead of `interface{}` for type consistency.
- Changed `Remove` methods in service and middleware to return errors for better error propagation.
- Improved documentation comments across multiple files for clarity and consistency.
- Replaced `fmt.Errorf` with `ewrap.Wrap` for error wrapping in serializer and stats collector.
- Fixed import order and formatting in test files.
- Enhanced worker pool logic and fixed worker resizing in `pool.go`.
- Improved stats collection and calculation logic in `stats` package.
- Minor bug fixes and code style improvements throughout the codebase.

Author: hyp3rd

.golangci.yaml

@@ -0,0 +1,266 @@
+---
+version: 2
+# Options for analysis running.
+run:
+  # Number of operating system threads (`GOMAXPROCS`) that can execute golangci-lint simultaneously.
+  # If it is explicitly set to 0 (i.e. not the default) then golangci-lint will automatically set the value to match Linux container CPU quota.
+  # Default: the number of logical CPUs in the machine
+  concurrency: 4
+  # Timeout for analysis, e.g. 30s, 5m.
+  # Default: 1m
+  timeout: 5m
+  # Exit code when at least one issue was found.
+  # Default: 1
+  issues-exit-code: 2
+  # Include test files or not.
+  # Default: true
+  tests: false
+  # List of build tags, all linters use it.
+  # Default: []
+  # build-tags:
+  #   - tag
+  # If set, we pass it to "go list -mod={option}". From "go help modules":
+  # If invoked with -mod=readonly, the go command is disallowed from the implicit
+  # automatic updating of go.mod described above. Instead, it fails when any changes
+  # to go.mod are needed. This setting is most useful to check that go.mod does
+  # not need updates, such as in a continuous integration and testing system.
+  # If invoked with -mod=vendor, the go command assumes that the vendor
+  # directory holds the correct copies of dependencies and ignores
+  # the dependency descriptions in go.mod.
+  #
+  # Allowed values: readonly|vendor|mod
+  # Default: ""
+  modules-download-mode: readonly
+  # Allow multiple parallel golangci-lint instances running.
+  # If false, golangci-lint acquires file lock on start.
+  # Default: false
+  allow-parallel-runners: true
+  # Allow multiple golangci-lint instances running, but serialize them around a lock.
+  # If false, golangci-lint exits with an error if it fails to acquire file lock on start.
+  # Default: false
+  allow-serial-runners: true
+  # Define the Go version limit.
+  # Mainly related to generics support since go1.18.
+  # Default: use Go version from the go.mod file, fallback on the env var `GOVERSION`, fallback on 1.17
+  go: "1.25.0"
+
+exclusions:
+  # Which file paths to exclude: they will be analyzed, but issues from them won't be reported.
+  # "/" will be replaced by the current OS file path separator to properly work on Windows.
+  # Default: []
+  paths:
+    - "cmd/*/test-*"
+
+linters:
+  # Enable specific linter
+  # https://golangci-lint.run/usage/linters/#enabled-by-default
+  default: all
+  enable:
+    - wsl_v5
+  disable:
+    - exhaustruct
+    - depguard
+    - ireturn
+    - lll
+    - tagliatelle
+    - wsl
+
+  settings:
+    cyclop:
+      # The maximal code complexity to report.
+      # Default: 10
+      max-complexity: 12
+    errcheck:
+      # Report about not checking of errors in type assertions: `a := b.(MyStruct)`.
+      # Such cases aren't reported by default.
+      # Default: false
+      check-type-assertions: true
+      # report about assignment of errors to blank identifier: `num, _ := strconv.Atoi(numStr)`.
+      # Such cases aren't reported by default.
+      # Default: false
+      check-blank: true
+      # To disable the errcheck built-in exclude list.
+      # See `-excludeonly` option in https://github.com/kisielk/errcheck#excluding-functions for details.
+      # Default: false
+      disable-default-exclusions: false
+      # List of functions to exclude from checking, where each entry is a single function to exclude.
+      # See https://github.com/kisielk/errcheck#excluding-functions for details.
+      exclude-functions:
+        - fmt.Fprintf
+        - fmt.Fprintln
+    funlen:
+      lines: 100
+    lll:
+      # Max line length, lines longer will be reported.
+      # '\t' is counted as 1 character by default, and can be changed with the tab-width option.
+      # Default: 120.
+      line-length: 150
+      # Tab width in spaces.
+      # Default: 1
+      tab-width: 1
+
+    ireturn:
+      # ireturn does not allow using `allow` and `reject` settings at the same time.
+      # Both settings are lists of the keywords and regular expressions matched to interface or package names.
+      # keywords:
+      # - `empty` for `any`
+      # - `error` for errors
+      # - `stdlib` for standard library
+      # - `anon` for anonymous interfaces
+      # - `generic` for generic interfaces added in go 1.18
+
+      # By default, it allows using errors, empty interfaces, anonymous interfaces,
+      # and interfaces provided by the standard library.
+      allow:
+        - anon
+        - error
+        - empty
+        - stdlib
+        # You can specify idiomatic endings for interface
+        - (or|er|ry)$
+
+    wrapcheck:
+      # An array of strings that specify globs of packages to ignore.
+      # Default: []
+      ignore-package-globs:
+        - github.com/hyp3rd/*
+        - github.com/gofiber/fiber/*
+
+    varnamelen:
+      # The longest distance, in source lines, that is being considered a "small scope".
+      # Variables used in at most this many lines will be ignored.
+      # Default: 5
+      max-distance: 6
+      # The minimum length of a variable's name that is considered "long".
+      # Variable names that are at least this long will be ignored.
+      # Default: 3
+      min-name-length: 2
+      # Check method receivers.
+      # Default: false
+      check-receiver: false
+      # Check named return values.
+      # Default: false
+      check-return: true
+      # Check type parameters.
+      # Default: false
+      check-type-param: true
+      # Ignore "ok" variables that hold the bool return value of a type assertion.
+      # Default: false
+      ignore-type-assert-ok: true
+      # Ignore "ok" variables that hold the bool return value of a map index.
+      # Default: false
+      ignore-map-index-ok: true
+      # Ignore "ok" variables that hold the bool return value of a channel receive.
+      # Default: false
+      ignore-chan-recv-ok: true
+      # Optional list of variable names that should be ignored completely.
+      # Default: []
+      ignore-names:
+        - err
+      # Optional list of variable declarations that should be ignored completely.
+      # Entries must be in one of the following forms (see below for examples):
+      # - for variables, parameters, named return values, method receivers, or type parameters:
+      #   <name> <type>  (<type> can also be a pointer/slice/map/chan/...)
+      # - for constants: const <name>
+      #
+      # Default: []
+      ignore-decls:
+        - c echo.Context
+        - t testing.T
+        - f *foo.Bar
+        - e error
+        - i int
+        - const C
+        - r *http.Request
+        - w http.ResponseWriter
+        - T any
+        - m map[string]int
+
+  # Enable only fast linters from enabled linters set (first run won't be fast)
+  # Default: false
+  fast: false
+
+formatters:
+  enable:
+    # - gci
+    - gofumpt
+    - goimports
+    # - golines
+  # gci:
+  #   # Section configuration to compare against.
+  #   # Section names are case-insensitive and may contain parameters in ().
+  #   # The default order of sections is `standard > default > custom > blank > dot > alias > localmodule`,
+  #   # If `custom-order` is `true`, it follows the order of `sections` option.
+  #   # Default: ["standard", "default"]
+  #   sections:
+  #     - standard # Standard section: captures all standard packages.
+  #     - default # Default section: contains all imports that could not be matched to another section type.
+  #     - prefix(github.com/hyp3rd/ewrap) # Custom section: groups all imports with the specified Prefix.
+  #   # Checks that no inline comments are present.
+  #   # Default: false
+  #   no-inline-comments: false
+  #   # Checks that no prefix comments (comment lines above an import) are present.
+  #   # Default: false
+  #   no-prefix-comments: false
+  #   # Enable custom order of sections.
+  #   # If `true`, make the section order the same as the order of `sections`.
+  #   # Default: false
+  #   custom-order: true
+  #   # Drops lexical ordering for custom sections.
+  #   # Default: false
+  #   no-lex-order: false
+
+  goimports:
+    # A comma-separated list of prefixes, which, if set, checks import paths
+    # with the given prefixes are grouped after 3rd-party packages.
+    # Default: ""
+    local-prefixes: github.com/hyp3rd/ewrap
+
+  gofmt:
+  gofumpt:
+    # Module path which contains the source code being formatted.
+    # Default: ""
+    module-path: github.com/hyp3rd/ewrap
+    # Choose whether to use the extra rules.
+    # Default: false
+    extra-rules: true
+
+# output configuration options
+output:
+  # Print lines of code with issue.
+  # Default: true
+  print-issued-lines: true
+  # Print linter name in the end of issue text.
+  # Default: true
+  print-linter-name: true
+  # Add a prefix to the output file references.
+  # Default: ""
+  path-prefix: ""
+  # Sort results by the order defined in `sort-order`.
+  # Default: false
+  sort-results: true
+  # Order to use when sorting results.
+  # Require `sort-results` to `true`.
+  # Possible values: `file`, `linter`, and `severity`.
+  #
+  # If the severity values are inside the following list, they are ordered in this order:
+  #   1. error
+  #   2. warning
+  #   3. high
+  #   4. medium
+  #   5. low
+  # Either they are sorted alphabetically.
+  #
+  # Default: ["file"]
+  sort-order:
+    - linter
+    - severity
+    - file # filepath, line, and column.
+  # Show statistics per linter.
+  # Default: false
+  show-stats: true
+
+issues:
+  # Make issues output unique by line.
+  # Default: true
+  uniq-by-line: false

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+      - id: fix-byte-order-marker
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: check-yaml
+        files: .*\.(yaml|yml)$
+        exclude: docs/*
+        args: [--allow-multiple-documents]
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.37.1
+    hooks:
+      - id: yamllint
+        files: \.(yaml|yml)$
+        types: [file, yaml]
+        entry: yamllint -c ./.yamllint.yaml --strict -f parsable
+  - repo: local
+    hooks:
+      - id: golangci-lint
+        name: golangci-lint
+        language: system
+        entry: ./.pre-commit/golangci-lint-hook
+        require_serial: true
+      - id: unit-test
+        name: unit test
+        language: system
+        entry: ./.pre-commit/unit-test-hook
+        require_serial: true

.pre-commit/golangci-lint-hook

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -e
+
+# ######################################
+# Ensure that a go module is initialized if not, skip the tests
+# #######################################
+ensure_go_module_initialized() {
+	if [[ ! -f go.mod ]]; then
+		echo "go.mod file not found, skipping the tests..."
+		exit 0
+	fi
+}
+
+# #######################################
+# Constants
+# #######################################
+GO_BIN_PATH="$(go env GOPATH)/bin"
+GOLANGCI_LINT_INSTALL_URL="https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh"
+GOLANGCI_LINT_VERSION="v2.4.0"
+
+# #######################################
+# Install dependencies to run the pre-commit hook
+# #######################################
+install_dependencies() {
+	# check if golangci-lint is installed or not
+	if ! command -v golangci-lint >/dev/null 2>&1; then
+		echo "installing golangci-lint ${GOLANGCI_LINT_VERSION}..."
+
+		# binary will be $(go env GOPATH)/bin/golangci-lint
+		curl -sSfL "${GOLANGCI_LINT_INSTALL_URL}" | sh -s -- -b "$(go env GOPATH)/bin" "${GOLANGCI_LINT_VERSION}"
+
+		echo "Installed golangci-lint ${GOLANGCI_LINT_VERSION}"
+
+		"$(go env GOPATH)"/bin/golangci-lint --version
+
+		# export the golangci-lint path to the PATH variable
+		export PATH="${GO_BIN_PATH}:${PATH}"
+	else
+		echo "golangci-lint is already installed"
+	fi
+}
+
+# #######################################
+# Run the pre-commit
+# #######################################
+hook() {
+	install_dependencies
+
+	# get the root of the project
+	local root_dir
+	root_dir=$(git rev-parse --show-toplevel)
+
+	# run the pre-commit hook
+	pushd "${root_dir}" || exit
+
+	echo "Running golangci-lint..."
+	golangci-lint run ./... || exit 1
+
+	popd >/dev/null || exit
+}
+
+cat <<EOF
+golangci-lint hook
+=============================================================================
+
+This hook ensures and runs golangci-lint on the project.
+It should be installed and run as a pre-commit hook.
+
+If golangci-lint finds any errors it will prevent the commit.
+=============================================================================
+
+EOF
+
+# run the hook if the go module is initialized
+ensure_go_module_initialized
+hook