add gerrit client wrapper

Authenticated go-gerrit client with startup credential validation via
the self account. apiError recovers Gerrit error response bodies the
library discards - on non-2xx go-gerrit returns the response unread
and unclosed, a contract pinned by a learning test - and attaches
status and message as structured fields.

All Gerrit traffic flows through this package; scoping restrictions
hook in here later.

Refs: #4

Author: xobotyi

internal/gerritclient/gerritclient.go

@@ -0,0 +1,93 @@
+// Package gerritclient wraps the go-gerrit REST client with the concerns the
+// library leaves to callers: credential validation at startup and recovery of
+// Gerrit error response bodies, which the library's errors discard. All
+// Gerrit traffic flows through this package — scoping restrictions hook in
+// here.
+package gerritclient
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"dev.gaijin.team/go/golib/e"
+	gerrit "github.com/andygrunwald/go-gerrit"
+
+	"dev.gaijin.team/go/go-gerrit-mcp/internal/config"
+)
+
+const (
+	httpTimeout = 30 * time.Second
+	// maxErrorBody caps how much of a Gerrit error response is attached to an
+	// error; Gerrit error bodies are short plain-text messages.
+	maxErrorBody = 4 << 10
+)
+
+// Sentinels for the two startup failure classes.
+var (
+	ErrClientInit   = e.New("create gerrit client")
+	ErrCredentials  = e.New("gerrit credential validation")
+	errEmptyAccount = e.New("gerrit returned an empty account")
+)
+
+// Client is the process-wide authenticated Gerrit API client.
+type Client struct {
+	gerrit *gerrit.Client
+	self   gerrit.AccountInfo
+}
+
+// New builds an authenticated client and validates the credentials against
+// the instance by fetching the calling account. A failure is reported with
+// Gerrit's own message where one exists.
+func New(ctx context.Context, cfg *config.Config) (*Client, error) {
+	g, err := gerrit.NewClient(ctx, cfg.GerritURL, &http.Client{Timeout: httpTimeout})
+	if err != nil {
+		return nil, ErrClientInit.Wrap(err)
+	}
+
+	g.Authentication.SetBasicAuth(cfg.Username, cfg.Token)
+
+	self, resp, err := g.Accounts.GetAccount(ctx, "self")
+	if err != nil {
+		return nil, ErrCredentials.Wrap(apiError(resp, err))
+	}
+
+	if self == nil {
+		return nil, ErrCredentials.Wrap(errEmptyAccount)
+	}
+
+	return &Client{gerrit: g, self: *self}, nil
+}
+
+// Self reports the authenticated account as validated at startup.
+func (c *Client) Self() gerrit.AccountInfo {
+	return c.self
+}
+
+// apiError converts a go-gerrit response/error pair into an error carrying
+// Gerrit's own message. The library's error holds only the status line; the
+// response body — readable and unclosed on the error path — holds the reason
+// a human can act on.
+func apiError(resp *gerrit.Response, err error) error {
+	if resp == nil || resp.Body == nil {
+		return e.From(err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	res := e.From(err).WithField("status", resp.StatusCode)
+
+	body, readErr := io.ReadAll(io.LimitReader(resp.Body, maxErrorBody))
+	if readErr != nil {
+		return res
+	}
+
+	msg := strings.TrimSpace(string(gerrit.RemoveMagicPrefixLine(body)))
+	if msg != "" {
+		res = res.WithField("gerrit_message", msg)
+	}
+
+	return res
+}

internal/gerritclient/gerritclient_internal_test.go

@@ -0,0 +1,90 @@
+package gerritclient
+
+import (
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	gerrit "github.com/andygrunwald/go-gerrit"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	errAPICall     = errors.New("api call failed")
+	errConnRefused = errors.New("connection refused")
+)
+
+func errResponse(status int, body string) *gerrit.Response {
+	return &gerrit.Response{
+		Response: &http.Response{ //nolint:exhaustruct // synthetic response, only fields apiError reads
+			StatusCode: status,
+			Body:       io.NopCloser(strings.NewReader(body)),
+		},
+	}
+}
+
+func Test_apiError(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name       string
+		giveStatus int
+		giveBody   string
+		wantParts  []string
+	}{
+		{
+			name:       "404 plain body",
+			giveStatus: http.StatusNotFound,
+			giveBody:   "Not found: change 999",
+			wantParts:  []string{"status=404", "Not found: change 999", "api call failed"},
+		},
+		{
+			name:       "409 with xssi prefix",
+			giveStatus: http.StatusConflict,
+			giveBody:   ")]}'\nblocked by Verified",
+			wantParts:  []string{"status=409", "blocked by Verified"},
+		},
+		{
+			name:       "empty body keeps status only",
+			giveStatus: http.StatusBadRequest,
+			giveBody:   "",
+			wantParts:  []string{"status=400"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := apiError(errResponse(tt.giveStatus, tt.giveBody), errAPICall)
+
+			require.Error(t, err)
+
+			for _, part := range tt.wantParts {
+				assert.ErrorContains(t, err, part)
+			}
+		})
+	}
+
+	t.Run("nil response passes error through", func(t *testing.T) {
+		t.Parallel()
+
+		err := apiError(nil, errConnRefused)
+
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "connection refused")
+	})
+
+	t.Run("oversized body is truncated", func(t *testing.T) {
+		t.Parallel()
+
+		huge := strings.Repeat("x", maxErrorBody*2)
+		err := apiError(errResponse(http.StatusBadRequest, huge), errAPICall)
+
+		require.Error(t, err)
+		assert.LessOrEqual(t, len(err.Error()), maxErrorBody+256)
+	})
+}

internal/gerritclient/gerritclient_test.go

@@ -0,0 +1,84 @@
+package gerritclient_test
+
+import (
+	"encoding/base64"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"dev.gaijin.team/go/go-gerrit-mcp/internal/config"
+	"dev.gaijin.team/go/go-gerrit-mcp/internal/gerritclient"
+)
+
+func testConfig(url string) *config.Config {
+	return &config.Config{
+		GerritURL: url,
+		Username:  "bot",
+		Token:     "s3cret",
+		Groups:    []config.Group{config.GroupRead},
+	}
+}
+
+func basicAuth(user, pass string) string {
+	return "Basic " + base64.StdEncoding.EncodeToString([]byte(user+":"+pass))
+}
+
+func Test_New(t *testing.T) {
+	t.Parallel()
+
+	t.Run("validates credentials against self account", func(t *testing.T) {
+		t.Parallel()
+
+		var gotPath, gotAuth string
+
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			gotPath = r.URL.Path
+			gotAuth = r.Header.Get("Authorization")
+
+			w.Header().Set("Content-Type", "application/json")
+
+			_, _ = w.Write([]byte(")]}'\n{\"_account_id\":42,\"name\":\"Review Bot\",\"username\":\"bot\"}"))
+		}))
+		t.Cleanup(srv.Close)
+
+		client, err := gerritclient.New(t.Context(), testConfig(srv.URL))
+		require.NoError(t, err)
+
+		assert.Equal(t, "/a/accounts/self", gotPath)
+		assert.Equal(t, basicAuth("bot", "s3cret"), gotAuth)
+
+		self := client.Self()
+		assert.Equal(t, 42, self.AccountID)
+		assert.Equal(t, "bot", self.Username)
+	})
+
+	t.Run("bad credentials surface gerrit message", func(t *testing.T) {
+		t.Parallel()
+
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusUnauthorized)
+
+			_, _ = w.Write([]byte("Unauthorized: token expired"))
+		}))
+		t.Cleanup(srv.Close)
+
+		_, err := gerritclient.New(t.Context(), testConfig(srv.URL))
+
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "credential validation")
+		assert.ErrorContains(t, err, "401")
+		assert.ErrorContains(t, err, "token expired")
+	})
+
+	t.Run("invalid url fails client construction", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := gerritclient.New(t.Context(), testConfig(""))
+
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "create gerrit client")
+	})
+}

internal/gerritclient/learning_test.go

@@ -0,0 +1,47 @@
+package gerritclient_test
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	gerrit "github.com/andygrunwald/go-gerrit"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Test_Learning_GoGerritErrorBody pins the go-gerrit contract the wrapper's
+// error enrichment is built on: on a non-2xx response the library returns the
+// wrapped *Response alongside the error WITHOUT reading or closing the body,
+// so the caller can still read Gerrit's message from it. If an upgrade breaks
+// this test, apiError silently stops carrying Gerrit messages — redesign it.
+func Test_Learning_GoGerritErrorBody(t *testing.T) {
+	t.Parallel()
+
+	const gerritMessage = "change is not submittable: blocked by Code-Review"
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusConflict)
+
+		_, _ = w.Write([]byte(gerritMessage))
+	}))
+	t.Cleanup(srv.Close)
+
+	client, err := gerrit.NewClient(t.Context(), srv.URL, nil)
+	require.NoError(t, err)
+
+	_, resp, err := client.Changes.GetChange(t.Context(), "123", nil)
+
+	require.Error(t, err)
+	assert.ErrorContains(t, err, "409")
+
+	require.NotNil(t, resp)
+	require.NotNil(t, resp.Body)
+
+	body, readErr := io.ReadAll(resp.Body)
+	require.NoError(t, readErr)
+	require.NoError(t, resp.Body.Close())
+
+	assert.Equal(t, gerritMessage, string(body))
+}