Initial commit with boilerplate

.github/workflows/golangci-lint.yaml

@@ -0,0 +1,43 @@
+name: "Lint"
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**.go'
+      - '.golangci.yaml'
+  pull_request:
+    paths:
+      - '**.go'
+      - '.golangci.yaml'
+
+permissions:
+  contents: read
+
+jobs:
+  golangci:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: 'stable'
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v4
+        with:
+          version: v1.56
+
+      - name: Install Task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+          # Heavy usage of the action can result in workflow run failures caused by rate limiting.
+          # GitHub provides a more generous allowance for Authenticated API requests.
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: fmt
+        run: task fmt

.gitignore

@@ -0,0 +1,19 @@
+# Taskfile / local tools
+.task
+build
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Go workspace file
+go.work

.golangci.yaml

@@ -0,0 +1,184 @@
+# We may as well allow multiple golangci-lint invocations at once.
+run:
+  allow-parallel-runners: true
+
+# golangci-lint by default ignores some staticcheck and vet raised issues that
+# are actually important to catch. The following ensures that we do not ignore
+# those tools ever.
+issues:
+  exclude-rules:
+    - path: (.+)_test.go
+      linters:
+        - bodyclose
+        - stylecheck
+        - goconst
+        - gosec
+  exclude-use-default: false
+  max-same-issues: 0 # 0 is unlimited
+linters:
+  disable-all: true
+  enable:
+    # Enabled by default linters: we want all except errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    # Not enabled by default: we want a good chunk
+    - asasalint
+    - asciicheck
+    - bidichk
+    - bodyclose
+    - containedctx
+    - cyclop
+    - durationcheck
+    - errname
+    - errorlint
+    - exhaustive
+    - exhaustruct
+    - exportloopref
+    - gci
+    - gocheckcompilerdirectives
+    - gocognit
+    - goconst
+    - gocritic
+    - gocyclo
+    - gofmt
+    - gofumpt
+    - goimports
+    - goprintffuncname
+    - gosec
+    - misspell
+    - nakedret
+    - nilerr
+    - noctx
+    - nolintlint
+    - reassign
+    - revive
+    - rowserrcheck
+    - sqlclosecheck
+    - stylecheck
+    - tenv
+    - typecheck
+    - unconvert
+    - unparam
+    - usestdlibvars
+    - wastedassign
+    - whitespace
+linters-settings:
+  # A default case ensures we have checked everything. We should not require
+  # every enum to be checked if we want to default.
+  exhaustive:
+    default-signifies-exhaustive: true
+  # If we want to opt out of a lint, we require an explanation.
+  nolintlint:
+    allow-unused: false
+    require-explanation: true
+    require-specific: true
+  # We do not want every usage of fmt.Errorf to use %w.
+  errorlint:
+    errorf: false
+  # If gofumpt is run outside of a module, it assumes Go 1.0 rather than the
+  # latest Go. We always want the latest formatting.
+  #
+  # https://github.com/mvdan/gofumpt/issues/137
+  gofumpt:
+    lang-version: "1.22"
+  gosec:
+    excludes:
+      - G104 # unhandled errors, we exclude for the same reason we do not use errcheck
+  # Complexity analysis: the recommendations are to be between 10-20, with a
+  # default of 30 for gocyclo and gocognit, and a default of 10 for cyclop. We
+  # will choose the middle of the range for cyclo analysis, which should be
+  # good enough for a lot of cases. We can bump to 20 later if necessary.  The
+  # cognitive analysis is a bit overly sensitive for large switch statements
+  # (say a function just switches to return a bunch of different strings), so
+  # we will keep its larger default of 30.
+  #
+  # cyclop provides no extra benefit to gocyclo because we are not using
+  # package average, but that's a weird metric nothing else adds.
+  cyclop:
+    max-complexity: 16
+  gocyclo:
+    min-complexity: 30
+  gocognit:
+    min-complexity: 30
+  gci:
+    sections:
+      - standard # stdlib
+      - default # everything not std, not within project
+      - prefix(github.com/redpanda-data/common-go)
+  # Gocritic is a meta linter that has very good lints, and most of the
+  # experimental ones are very good too. There are only a few we want to opt
+  # out of specifically.
+  gocritic:
+    enabled-tags:
+      - diagnostic
+      - experimental
+      - opinionated
+      - performance
+      - style
+    disabled-checks:
+      - evalOrder
+      - importShadow
+      # disabled due to 1.18 failures
+      - hugeParam
+      - rangeValCopy
+      - typeDefFirst
+      - paramTypeCombine
+      - unnamedResult
+      #settings:
+      #  hugeParam:
+      #    sizeThreshold: 256
+      #  rangeValCopy:
+      #    sizeThreshold: 256
+  # Revive is yet another metalinter with a bunch of useful lints. The below
+  # opts in to all of the ones we would like to use.
+  revive:
+    ignore-generated-header: true
+    enable-all-rules: true
+    severity: warning
+    confidence: 0.7
+    rules:
+      # removed because replacing the version of a proto is easier if we use it
+      # as alias
+      - name: redundant-import-alias
+        disabled: true
+      - name: add-constant
+        disabled: true
+      - name: argument-limit
+        disabled: true
+      - name: banned-characters
+        disabled: true
+      - name: cognitive-complexity
+        disabled: true
+      - name: confusing-naming
+        disabled: true
+      - name: cyclomatic
+        disabled: true
+      - name: file-header
+        disabled: true
+      - name: flag-parameter
+        disabled: true
+      - name: function-result-limit
+        disabled: true
+      - name: function-length
+        disabled: true
+      - name: import-shadowing
+        disabled: true
+      - name: line-length-limit
+        disabled: true
+      - name: max-public-structs
+        disabled: true
+      - name: modifies-parameter
+        disabled: true
+      - name: nested-structs
+        disabled: true
+      - name: package-comments # https://github.com/mgechev/revive/issues/740; stylecheck's ST1000 is better
+        disabled: true
+      - name: redefines-builtin-id
+        disabled: true
+      - name: unhandled-error
+        disabled: true
+      - name: var-naming
+        disabled: true

README.md

@@ -1 +1,18 @@
-# common-go
+# Redpanda Common Go Repository
+
+Welcome to the Redpanda Common Go Repository! This repository serves as a hub 
+for sharing code across various Redpanda code bases. While the community 
+is welcome to utilize the code herein, please note that we do not offer 
+any guarantees, support, or consider feature requests.
+
+This repository is used to share code between different Redpanda code bases.
+It may be used by the community, but we do not provide any guarantees, support
+and won't consider any feature requests.
+
+## API Module
+
+The API Module contains a collection of helper functions designed to streamline 
+various tasks, including pagination, error construction, and boilerplate code 
+for the gRPC/connect API. These utilities are aimed at simplifying development 
+workflows within the Redpanda ecosystem. For detailed documentation, please 
+refer to the [./api] directory.

Taskfile.yaml

@@ -0,0 +1,59 @@
+version: "3"
+
+vars:
+  BUILD_ROOT: "{{ .ROOT_DIR }}/build"
+  GO_VERSION: 1.22.0
+  GO_BUILD_ROOT: '{{.BUILD_ROOT}}/go/{{.GO_VERSION}}'
+  MODULES:
+    sh: find . -maxdepth 2 -name go.mod -execdir pwd \;
+  PATH_PREFIX: PATH={{.BUILD_ROOT}}/bin:{{.GO_BUILD_ROOT}}/bin:{{.BUILD_ROOT}}/bin/go:$PATH GOBIN={{ .BUILD_ROOT }}/bin/go GOROOT=
+
+includes:
+  install: taskfiles/install.yaml
+
+tasks:
+  lint:
+    desc: Lint all Go code
+    deps: ['install:golangci-lint']
+    cmds:
+      - for: { var: MODULES }
+        task: lint:dir
+        vars:
+         DIRECTORY: '{{.ITEM}}'
+
+  lint:dir:
+    label: lint:dir {{ .DIRECTORY }}
+    desc: Lint Go code on the provided directory
+    deps: ['install:golangci-lint']
+    vars:
+      DIRECTORY: '{{ .DIRECTORY }}'
+    sources:
+      - '{{ .DIRECTORY }}/**/*.go'
+    cmds:
+      - '{{ .BUILD_ROOT }}/bin/go/goimports -l -w -local "github.com/redpanda-data/common-go" {{.DIRECTORY}}'
+
+  fmt:
+    desc: Run all formatters
+    cmds:
+      - for: { var: MODULES }
+        task: fmt:dir
+        vars:
+          DIRECTORY: '{{.ITEM}}'
+
+  fmt:dir:
+    label: fmt:dir {{ .DIRECTORY }}
+    desc: Run all of the Go formatters on the provided directory, excluding any generated folders
+    deps:
+      - 'install:go'
+      - 'install:gofumpt'
+      - 'install:goimports'
+      - 'install:gci'
+    vars:
+      DIRECTORY: '{{ .DIRECTORY }}'
+    sources:
+      - '{{ .DIRECTORY }}/**/*.go'
+    cmds:
+      - '{{ .BUILD_ROOT }}/bin/go/goimports -l -w -local "github.com/redpanda-data/common-go" {{.DIRECTORY}}'
+      - '{{ .BUILD_ROOT }}/bin/go/gofumpt -l -w {{.DIRECTORY}}'
+      - '{{ .BUILD_ROOT }}/bin/go/gci write -s default -s standard -s "prefix(github.com/redpanda-data/common-go)" {{.DIRECTORY}}'
+      - if [[ $CI == "true" ]]; then git --no-pager diff --exit-code; fi

api/README.md

@@ -0,0 +1,30 @@
+# API
+
+The API package contains code that can be shared among multiple projects that are involved 
+in serving or consuming any public or internal Redpanda API. Redpanda uses connectrpc
+and therefore this project is heavily built around that.
+
+## Errors
+
+The errors package contains several helpers for constructing new connectrpc errors,
+as well as custom HTTP error handler for the gRPC gateway.
+
+**Creating new Connect errors:**
+
+```go
+err := apierrors.NewConnectError(
+	connect.CodeUnimplemented,
+	errors.New("the redpanda admin api must be configured to use this endpoint"),
+	apierrors.NewErrorInfo(
+            apierrors.DomainDataplane,
+            v1alpha1.Reason_REASON_FEATURE_NOT_CONFIGURED.String(),
+        ),
+	apierrors.NewHelp(apierrors.NewHelpLink("Redpanda Console Configuration Reference", "https://docs.redpanda.com/current/reference/console/config/")),
+)
+```
+
+**Mount Redpanda gRPC Gateway Error Handler**
+
+```go
+
+```