feat: api - add a new endpoint - GET /api/v2/versions/{versionCode}/servers/{serverKey}/players (#6)

Reviewed-on: twhelp/corev3#6

api/openapi3.yml

@@ -166,6 +166,25 @@ paths:
           $ref: "#/components/responses/GetTribeResponse"
         default:
           $ref: "#/components/responses/ErrorResponse"
+  /v2/versions/{versionCode}/servers/{serverKey}/players:
+    get:
+      operationId: listPlayers
+      tags:
+        - versions
+        - servers
+        - players
+      description: List players
+      parameters:
+        - $ref: "#/components/parameters/VersionCodePathParam"
+        - $ref: "#/components/parameters/ServerKeyPathParam"
+        - $ref: "#/components/parameters/CursorQueryParam"
+        - $ref: "#/components/parameters/LimitQueryParam"
+        - $ref: "#/components/parameters/PlayerDeletedQueryParam"
+      responses:
+        200:
+          $ref: "#/components/responses/ListPlayersResponse"
+        default:
+          $ref: "#/components/responses/ErrorResponse"
 components:
   schemas:
     Error:
@@ -920,6 +939,76 @@ components:
         deletedAt:
           type: string
           format: date-time
+    PlayerOpponentsDefeated:
+      allOf:
+        - $ref: "#/components/schemas/TribeOpponentsDefeated"
+        - type: object
+          required:
+            - rankSup
+            - scoreSup
+          properties:
+            rankSup:
+              type: integer
+            scoreSup:
+              type: integer
+    Player:
+      type: object
+      required:
+        - id
+        - name
+        - rank
+        - points
+        - numVillages
+        - profileUrl
+        - lastActivityAt
+        - bestRank
+        - bestRankAt
+        - mostPoints
+        - mostPointsAt
+        - mostVillages
+        - mostVillagesAt
+        - opponentsDefeated
+        - createdAt
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        rank:
+          type: integer
+        points:
+          type: integer
+        numVillages:
+          type: integer
+        profileUrl:
+          type: string
+          format: uri
+        lastActivityAt:
+          type: string
+          format: date-time
+        bestRank:
+          type: integer
+        bestRankAt:
+          type: string
+          format: date-time
+        mostPoints:
+          type: integer
+        mostPointsAt:
+          type: string
+          format: date-time
+        mostVillages:
+          type: integer
+        mostVillagesAt:
+          type: string
+          format: date-time
+        opponentsDefeated:
+          $ref: "#/components/schemas/PlayerOpponentsDefeated"
+        createdAt:
+          type: string
+          format: date-time
+        deletedAt:
+          type: string
+          format: date-time
     Cursor:
       type: object
       x-go-type-skip-optional-pointer: true
@@ -1003,6 +1092,14 @@ components:
         items:
           type: string
         maxItems: 100
+    PlayerDeletedQueryParam:
+      name: deleted
+      in: query
+      description: true=only deleted players, false=only existing players,
+        by default both existing and deleted players are returned
+      schema:
+        type: boolean
+      required: false
     VersionCodePathParam:
       in: path
       name: versionCode
@@ -1134,6 +1231,21 @@ components:
             properties:
               data:
                 $ref: "#/components/schemas/Tribe"
+    ListPlayersResponse:
+      description: ""
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/PaginationResponse"
+              - type: object
+                required:
+                  - data
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Player"
     ErrorResponse:
       description: Default error response.
       content:

cmd/twhelp/cmd_serve.go

@@ -107,11 +107,13 @@ var cmdServe = &cli.Command{
 		versionRepo := adapter.NewVersionBunRepository(bunDB)
 		serverRepo := adapter.NewServerBunRepository(bunDB)
 		tribeRepo := adapter.NewTribeBunRepository(bunDB)
+		playerRepo := adapter.NewPlayerBunRepository(bunDB)
 
 		// services
 		versionSvc := app.NewVersionService(versionRepo)
 		serverSvc := app.NewServerService(serverRepo, nil, nil)
 		tribeSvc := app.NewTribeService(tribeRepo, nil, nil)
+		playerSvc := app.NewPlayerService(playerRepo, nil, nil, nil)
 
 		// health
 		h := health.New()
@@ -138,6 +140,7 @@ var cmdServe = &cli.Command{
 					versionSvc,
 					serverSvc,
 					tribeSvc,
+					playerSvc,
 					port.WithOpenAPIConfig(oapiCfg),
 				))
 

internal/port/handler_http_api.go

@@ -16,6 +16,7 @@ type apiHTTPHandler struct {
 	versionSvc    *app.VersionService
 	serverSvc     *app.ServerService
 	tribeSvc      *app.TribeService
+	playerSvc     *app.PlayerService
 	errorRenderer apiErrorRenderer
 	openAPISchema func() (*openapi3.T, error)
 }
@@ -30,6 +31,7 @@ func NewAPIHTTPHandler(
 	versionSvc *app.VersionService,
 	serverSvc *app.ServerService,
 	tribeSvc *app.TribeService,
+	playerSvc *app.PlayerService,
 	opts ...APIHTTPHandlerOption,
 ) http.Handler {
 	cfg := newAPIHTTPHandlerConfig(opts...)
@@ -38,6 +40,7 @@ func NewAPIHTTPHandler(
 		versionSvc: versionSvc,
 		serverSvc:  serverSvc,
 		tribeSvc:   tribeSvc,
+		playerSvc:  playerSvc,
 		openAPISchema: sync.OnceValues(func() (*openapi3.T, error) {
 			return getOpenAPISchema(cfg.openAPI)
 		}),

internal/port/handler_http_api_player.go

@@ -0,0 +1,84 @@
+package port
+
+import (
+	"net/http"
+	"strconv"
+
+	"gitea.dwysokinski.me/twhelp/corev3/internal/domain"
+	"gitea.dwysokinski.me/twhelp/corev3/internal/port/internal/apimodel"
+)
+
+func (h *apiHTTPHandler) ListPlayers(
+	w http.ResponseWriter,
+	r *http.Request,
+	_ apimodel.VersionCodePathParam,
+	serverKey apimodel.ServerKeyPathParam,
+	params apimodel.ListPlayersParams,
+) {
+	domainParams := domain.NewListPlayersParams()
+
+	if err := domainParams.SetSort([]domain.PlayerSort{domain.PlayerSortIDASC}); err != nil {
+		h.errorRenderer.withErrorPathFormatter(formatListPlayersErrorPath).render(w, r, err)
+		return
+	}
+
+	if err := domainParams.SetServerKeys([]string{serverKey}); err != nil {
+		h.errorRenderer.withErrorPathFormatter(formatListPlayersErrorPath).render(w, r, err)
+		return
+	}
+
+	if params.Deleted != nil {
+		if err := domainParams.SetDeleted(domain.NullBool{
+			Value: *params.Deleted,
+			Valid: true,
+		}); err != nil {
+			h.errorRenderer.withErrorPathFormatter(formatListPlayersErrorPath).render(w, r, err)
+			return
+		}
+	}
+
+	if params.Limit != nil {
+		if err := domainParams.SetLimit(*params.Limit); err != nil {
+			h.errorRenderer.withErrorPathFormatter(formatListPlayersErrorPath).render(w, r, err)
+			return
+		}
+	}
+
+	if params.Cursor != nil {
+		if err := domainParams.SetEncodedCursor(*params.Cursor); err != nil {
+			h.errorRenderer.withErrorPathFormatter(formatListPlayersErrorPath).render(w, r, err)
+			return
+		}
+	}
+
+	res, err := h.playerSvc.List(r.Context(), domainParams)
+	if err != nil {
+		h.errorRenderer.render(w, r, err)
+		return
+	}
+
+	renderJSON(w, r, http.StatusOK, apimodel.NewListPlayersResponse(res))
+}
+
+func formatListPlayersErrorPath(segments []errorPathSegment) []string {
+	if segments[0].model != "ListPlayersParams" {
+		return nil
+	}
+
+	switch segments[0].field {
+	case "cursor":
+		return []string{"$query", "cursor"}
+	case "limit":
+		return []string{"$query", "limit"}
+	case "deleted":
+		return []string{"$query", "deleted"}
+	case "sort":
+		path := []string{"$query", "sort"}
+		if segments[0].index >= 0 {
+			path = append(path, strconv.Itoa(segments[0].index))
+		}
+		return path
+	default:
+		return nil
+	}
+}

internal/port/handler_http_api_player_test.go

@@ -0,0 +1,499 @@
+package port_test
+
+import (
+	"cmp"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+
+	"gitea.dwysokinski.me/twhelp/corev3/internal/domain"
+	"gitea.dwysokinski.me/twhelp/corev3/internal/domain/domaintest"
+	"gitea.dwysokinski.me/twhelp/corev3/internal/port/internal/apimodel"
+	"github.com/brianvoe/gofakeit/v6"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const endpointListPlayers = "/v2/versions/%s/servers/%s/players"
+
+func TestListPlayers(t *testing.T) {
+	t.Parallel()
+
+	handler := newAPIHTTPHandler(t)
+	players := getAllPlayers(t, handler)
+	var server serverWithVersion
+
+	for _, p := range players {
+		if p.DeletedAt != nil {
+			server = p.Server
+			break
+		}
+	}
+
+	require.NotZero(t, server)
+
+	tests := []struct {
+		name        string
+		reqModifier func(t *testing.T, req *http.Request)
+		assertResp  func(t *testing.T, req *http.Request, resp *http.Response)
+	}{
+		{
+			name: "OK: without params",
+			assertResp: func(t *testing.T, _ *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ListPlayersResponse](t, resp.Body)
+				assert.Zero(t, body.Cursor.Next)
+				assert.NotZero(t, body.Cursor.Self)
+				assert.NotZero(t, body.Data)
+				assert.True(t, slices.IsSortedFunc(body.Data, func(a, b apimodel.Player) int {
+					return cmp.Compare(a.Id, b.Id)
+				}))
+			},
+		},
+		{
+			name: "OK: limit=1",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("limit", "1")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ListPlayersResponse](t, resp.Body)
+				assert.NotZero(t, body.Cursor.Next)
+				assert.NotZero(t, body.Cursor.Self)
+				assert.NotZero(t, body.Data)
+				limit, err := strconv.Atoi(req.URL.Query().Get("limit"))
+				require.NoError(t, err)
+				assert.Len(t, body.Data, limit)
+			},
+		},
+		{
+			name: "OK: limit=1 cursor",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+
+				q := req.URL.Query()
+				q.Set("limit", "1")
+				req.URL.RawQuery = q.Encode()
+
+				resp := doCustomRequest(handler, req.Clone(req.Context()))
+				defer resp.Body.Close()
+				body := decodeJSON[apimodel.ListPlayersResponse](t, resp.Body)
+				require.NotEmpty(t, body.Cursor.Next)
+
+				q.Set("cursor", body.Cursor.Next)
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ListPlayersResponse](t, resp.Body)
+				assert.Equal(t, req.URL.Query().Get("cursor"), body.Cursor.Self)
+				limit, err := strconv.Atoi(req.URL.Query().Get("limit"))
+				require.NoError(t, err)
+				assert.Len(t, body.Data, limit)
+			},
+		},
+		{
+			name: "OK: deleted=false",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("deleted", "false")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, _ *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ListPlayersResponse](t, resp.Body)
+				assert.NotZero(t, body.Data)
+				for _, tr := range body.Data {
+					assert.Nil(t, tr.DeletedAt)
+				}
+			},
+		},
+		{
+			name: "OK: deleted=true",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("deleted", "true")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, _ *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ListPlayersResponse](t, resp.Body)
+				assert.NotZero(t, body.Data)
+				for _, tr := range body.Data {
+					assert.NotNil(t, tr.DeletedAt)
+				}
+			},
+		},
+		{
+			name: "ERR: limit is not a string",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("limit", "asd")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code: "invalid-param-format",
+							Message: fmt.Sprintf(
+								"error binding string parameter: strconv.ParseInt: parsing \"%s\": invalid syntax",
+								req.URL.Query().Get("limit"),
+							),
+							Path: []string{"$query", "limit"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: limit < 1",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("limit", "0")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				limit, err := strconv.Atoi(req.URL.Query().Get("limit"))
+				require.NoError(t, err)
+				domainErr := domain.MinGreaterEqualError{
+					Min:     1,
+					Current: limit,
+				}
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Params: map[string]any{
+								"current": float64(domainErr.Current),
+								"min":     float64(domainErr.Min),
+							},
+							Path: []string{"$query", "limit"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: limit > 200",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("limit", "201")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				limit, err := strconv.Atoi(req.URL.Query().Get("limit"))
+				require.NoError(t, err)
+				domainErr := domain.MaxLessEqualError{
+					Max:     200,
+					Current: limit,
+				}
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Params: map[string]any{
+								"current": float64(domainErr.Current),
+								"max":     float64(domainErr.Max),
+							},
+							Path: []string{"$query", "limit"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: len(cursor) < 1",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("cursor", "")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				domainErr := domain.LenOutOfRangeError{
+					Min:     1,
+					Max:     1000,
+					Current: len(req.URL.Query().Get("cursor")),
+				}
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Params: map[string]any{
+								"current": float64(domainErr.Current),
+								"max":     float64(domainErr.Max),
+								"min":     float64(domainErr.Min),
+							},
+							Path: []string{"$query", "cursor"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: len(cursor) > 1000",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("cursor", gofakeit.LetterN(1001))
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				domainErr := domain.LenOutOfRangeError{
+					Min:     1,
+					Max:     1000,
+					Current: len(req.URL.Query().Get("cursor")),
+				}
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Params: map[string]any{
+								"current": float64(domainErr.Current),
+								"max":     float64(domainErr.Max),
+								"min":     float64(domainErr.Min),
+							},
+							Path: []string{"$query", "cursor"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: invalid cursor",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("cursor", gofakeit.LetterN(100))
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, _ *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				var domainErr domain.Error
+				require.ErrorAs(t, domain.ErrInvalidCursor, &domainErr)
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Path:    []string{"$query", "cursor"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: deleted is not a valid boolean",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				q := req.URL.Query()
+				q.Set("deleted", "asd")
+				req.URL.RawQuery = q.Encode()
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code: "invalid-param-format",
+							Message: fmt.Sprintf(
+								"error binding string parameter: strconv.ParseBool: parsing \"%s\": invalid syntax",
+								req.URL.Query().Get("deleted"),
+							),
+							Path: []string{"$query", "deleted"},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: version not found",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				req.URL.Path = fmt.Sprintf(endpointListPlayers, domaintest.RandVersionCode(), server.Key)
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				pathSegments := strings.Split(req.URL.Path, "/")
+				require.Len(t, pathSegments, 7)
+				domainErr := domain.VersionNotFoundError{
+					VersionCode: pathSegments[3],
+				}
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Params: map[string]any{
+								"code": domainErr.VersionCode,
+							},
+						},
+					},
+				}, body)
+			},
+		},
+		{
+			name: "ERR: server not found",
+			reqModifier: func(t *testing.T, req *http.Request) {
+				t.Helper()
+				req.URL.Path = fmt.Sprintf(endpointListPlayers, server.Version.Code, domaintest.RandServerKey())
+			},
+			assertResp: func(t *testing.T, req *http.Request, resp *http.Response) {
+				t.Helper()
+
+				assert.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+				// body
+				body := decodeJSON[apimodel.ErrorResponse](t, resp.Body)
+				pathSegments := strings.Split(req.URL.Path, "/")
+				require.Len(t, pathSegments, 7)
+				domainErr := domain.ServerNotFoundError{
+					Key: pathSegments[5],
+				}
+				assert.Equal(t, apimodel.ErrorResponse{
+					Errors: []apimodel.Error{
+						{
+							Code:    domainErr.Code(),
+							Message: domainErr.Error(),
+							Params: map[string]any{
+								"key": domainErr.Key,
+							},
+						},
+					},
+				}, body)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			req := httptest.NewRequest(
+				http.MethodGet,
+				fmt.Sprintf(endpointListPlayers, server.Version.Code, server.Key),
+				nil,
+			)
+			if tt.reqModifier != nil {
+				tt.reqModifier(t, req)
+			}
+
+			resp := doCustomRequest(handler, req)
+			defer resp.Body.Close()
+			tt.assertResp(t, req, resp)
+		})
+	}
+}
+
+type playerWithServer struct {
+	apimodel.Player
+	Server serverWithVersion
+}
+
+func getAllPlayers(tb testing.TB, h http.Handler) []playerWithServer {
+	tb.Helper()
+
+	servers := getAllServers(tb, h)
+
+	var players []playerWithServer
+
+	for _, s := range servers {
+		resp := doRequest(h, http.MethodGet, fmt.Sprintf(endpointListPlayers, s.Version.Code, s.Key), nil)
+		require.Equal(tb, http.StatusOK, resp.StatusCode)
+
+		for _, p := range decodeJSON[apimodel.ListPlayersResponse](tb, resp.Body).Data {
+			players = append(players, playerWithServer{
+				Player: p,
+				Server: s,
+			})
+		}
+
+		_ = resp.Body.Close()
+	}
+
+	require.NotZero(tb, players)
+
+	return players
+}

internal/port/handler_http_api_test.go

@@ -35,11 +35,13 @@ func newAPIHTTPHandler(tb testing.TB, opts ...func(cfg *apiHTTPHandlerConfig)) h
 	versionRepo := adapter.NewVersionBunRepository(bunDB)
 	serverRepo := adapter.NewServerBunRepository(bunDB)
 	tribeRepo := adapter.NewTribeBunRepository(bunDB)
+	playerRepo := adapter.NewPlayerBunRepository(bunDB)
 
 	return port.NewAPIHTTPHandler(
 		app.NewVersionService(versionRepo),
 		app.NewServerService(serverRepo, nil, nil),
 		app.NewTribeService(tribeRepo, nil, nil),
+		app.NewPlayerService(playerRepo, nil, nil, nil),
 		cfg.options...,
 	)
 }

internal/port/internal/apimodel/player.go

@@ -0,0 +1,62 @@
+package apimodel
+
+import (
+	"gitea.dwysokinski.me/twhelp/corev3/internal/domain"
+)
+
+func NewPlayerOpponentsDefeated(od domain.OpponentsDefeated) PlayerOpponentsDefeated {
+	return PlayerOpponentsDefeated{
+		RankAtt:    od.RankAtt(),
+		RankDef:    od.RankDef(),
+		RankSup:    od.RankSup(),
+		RankTotal:  od.RankTotal(),
+		ScoreAtt:   od.ScoreAtt(),
+		ScoreDef:   od.ScoreDef(),
+		ScoreSup:   od.ScoreSup(),
+		ScoreTotal: od.ScoreTotal(),
+	}
+}
+
+func NewPlayer(p domain.Player) Player {
+	converted := Player{
+		BestRank:          p.BestRank(),
+		BestRankAt:        p.BestRankAt(),
+		CreatedAt:         p.CreatedAt(),
+		Id:                p.ID(),
+		LastActivityAt:    p.LastActivityAt(),
+		MostPoints:        p.MostPoints(),
+		MostPointsAt:      p.MostPointsAt(),
+		MostVillages:      p.MostVillages(),
+		MostVillagesAt:    p.MostVillagesAt(),
+		Name:              p.Name(),
+		NumVillages:       p.NumVillages(),
+		OpponentsDefeated: NewPlayerOpponentsDefeated(p.OD()),
+		Points:            p.Points(),
+		ProfileUrl:        p.ProfileURL().String(),
+		Rank:              p.Rank(),
+	}
+
+	if deletedAt := p.DeletedAt(); !deletedAt.IsZero() {
+		converted.DeletedAt = &deletedAt
+	}
+
+	return converted
+}
+
+func NewListPlayersResponse(res domain.ListPlayersResult) ListPlayersResponse {
+	players := res.Players()
+
+	resp := ListPlayersResponse{
+		Data: make([]Player, 0, len(players)),
+		Cursor: Cursor{
+			Next: res.Next().Encode(),
+			Self: res.Self().Encode(),
+		},
+	}
+
+	for _, p := range players {
+		resp.Data = append(resp.Data, NewPlayer(p))
+	}
+
+	return resp
+}