feat: Cookies API (minekube#535)

* feat: add cookies

* refactor: rework cookie system

* refactor: rename variables for clarity

* refactor: use sync.Map and update to 1.21.5

* refactor: enhance cookie handling and viewer context management

- Introduced context support in the Viewer interface for better management of player connections.
- Updated cookie storage and request handling to include validation for player protocol and state.
- Replaced deprecated methods with new implementations for improved clarity and functionality.
- Enhanced event handling for cookie responses, allowing for more robust interaction with client requests.
- Removed obsolete cookie handling code to streamline the system.

* feat: implement cookie storage and request handling

- Added StoreCookie and RequestCookie RPC methods to the GateService for managing cookies on players' clients.
- Introduced corresponding request and response message types for cookie operations in the API.
- Updated documentation to reflect new cookie handling features.
- Enhanced event handling for cookie requests and storage, ensuring proper player context management.

* add test and format code

---------

Co-authored-by: BorisP1234 <borispieneman@yahoo.com>
Co-authored-by: Boris <132673559+BorisP1234@users.noreply.github.com>

Author: robinbraemer

.web/docs/developers/api/gen/definition.gen.md

@@ -17,7 +17,11 @@
     - [Player](#minekube-gate-v1-Player)
     - [RegisterServerRequest](#minekube-gate-v1-RegisterServerRequest)
     - [RegisterServerResponse](#minekube-gate-v1-RegisterServerResponse)
+    - [RequestCookieRequest](#minekube-gate-v1-RequestCookieRequest)
+    - [RequestCookieResponse](#minekube-gate-v1-RequestCookieResponse)
     - [Server](#minekube-gate-v1-Server)
+    - [StoreCookieRequest](#minekube-gate-v1-StoreCookieRequest)
+    - [StoreCookieResponse](#minekube-gate-v1-StoreCookieResponse)
     - [UnregisterServerRequest](#minekube-gate-v1-UnregisterServerRequest)
     - [UnregisterServerResponse](#minekube-gate-v1-UnregisterServerResponse)
 
@@ -222,6 +226,37 @@ RegisterServerResponse is the response for RegisterServer method.
 
 
 
+<a name="minekube-gate-v1-RequestCookieRequest"></a>
+
+### RequestCookieRequest
+RequestCookieRequest is the request for RequestCookie method.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| player | [string](#string) |  | The player&#39;s username or ID |
+| key | [string](#string) |  | The key of the cookie in format `namespace:key` |
+
+
+
+
+
+
+<a name="minekube-gate-v1-RequestCookieResponse"></a>
+
+### RequestCookieResponse
+RequestCookieResponse is the response for RequestCookie method.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| payload | [bytes](#bytes) |  | The payload of the cookie. May be empty if the cookie is not found. |
+
+
+
+
+
+
 <a name="minekube-gate-v1-Server"></a>
 
 ### Server
@@ -239,6 +274,33 @@ Server represents a backend server where Gate can connect players to.
 
 
 
+<a name="minekube-gate-v1-StoreCookieRequest"></a>
+
+### StoreCookieRequest
+StoreCookieRequest is the request for StoreCookie method.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| player | [string](#string) |  | The player&#39;s username or ID |
+| key | [string](#string) |  | The key of the cookie in format `namespace:key` |
+| payload | [bytes](#bytes) |  | The payload to store. Passing an empty payload will remove the cookie. |
+
+
+
+
+
+
+<a name="minekube-gate-v1-StoreCookieResponse"></a>
+
+### StoreCookieResponse
+StoreCookieResponse is the response for StoreCookie method.
+
+
+
+
+
+
 <a name="minekube-gate-v1-UnregisterServerRequest"></a>
 
 ### UnregisterServerRequest
@@ -287,6 +349,8 @@ All methods follow standard gRPC error codes and include detailed error messages
 | UnregisterServer | [UnregisterServerRequest](#minekube-gate-v1-UnregisterServerRequest) | [UnregisterServerResponse](#minekube-gate-v1-UnregisterServerResponse) | UnregisterServer removes a server from the proxy. Returns NOT_FOUND if no matching server is found. Returns INVALID_ARGUMENT if neither name nor address is provided. |
 | ConnectPlayer | [ConnectPlayerRequest](#minekube-gate-v1-ConnectPlayerRequest) | [ConnectPlayerResponse](#minekube-gate-v1-ConnectPlayerResponse) | ConnectPlayer connects a player to a specified server. Returns NOT_FOUND if either the player or target server doesn&#39;t exist. Returns FAILED_PRECONDITION if the connection attempt fails. |
 | DisconnectPlayer | [DisconnectPlayerRequest](#minekube-gate-v1-DisconnectPlayerRequest) | [DisconnectPlayerResponse](#minekube-gate-v1-DisconnectPlayerResponse) | DisconnectPlayer disconnects a player from the proxy. Returns NOT_FOUND if the player doesn&#39;t exist. Returns INVALID_ARGUMENT if the reason text is malformed. |
+| StoreCookie | [StoreCookieRequest](#minekube-gate-v1-StoreCookieRequest) | [StoreCookieResponse](#minekube-gate-v1-StoreCookieResponse) | StoreCookie stores a cookie on a player&#39;s client. Returns NOT_FOUND if the player doesn&#39;t exist. Passing an empty payload will remove the cookie. |
+| RequestCookie | [RequestCookieRequest](#minekube-gate-v1-RequestCookieRequest) | [RequestCookieResponse](#minekube-gate-v1-RequestCookieResponse) | RequestCookie requests a cookie from a player&#39;s client. The payload in RequestCookieResponse may be empty if the cookie is not found. |
 
 
 

api/minekube/gate/v1/gate_service.proto

@@ -37,8 +37,47 @@ service GateService {
   // Returns NOT_FOUND if the player doesn't exist.
   // Returns INVALID_ARGUMENT if the reason text is malformed.
   rpc DisconnectPlayer(DisconnectPlayerRequest) returns (DisconnectPlayerResponse);
+
+  // StoreCookie stores a cookie on a player's client.
+  // Returns NOT_FOUND if the player doesn't exist.
+  // Passing an empty payload will remove the cookie.
+  rpc StoreCookie(StoreCookieRequest) returns (StoreCookieResponse);
+
+  // RequestCookie requests a cookie from a player's client.
+  // The payload in RequestCookieResponse may be empty if the cookie is not found.
+  rpc RequestCookie(RequestCookieRequest) returns (RequestCookieResponse);
 }
 
+// StoreCookieRequest is the request for StoreCookie method.
+message StoreCookieRequest {
+  // The player's username or ID
+  string player = 1;
+  // The key of the cookie in format `namespace:key`
+  string key = 2;
+  // The payload to store.
+  // Passing an empty payload will remove the cookie.
+  bytes payload = 3;
+}
+
+// StoreCookieResponse is the response for StoreCookie method.
+message StoreCookieResponse {}
+
+// RequestCookieRequest is the request for RequestCookie method.
+message RequestCookieRequest {
+  // The player's username or ID
+  string player = 1;
+  // The key of the cookie in format `namespace:key`
+  string key = 2;
+}
+
+// RequestCookieResponse is the response for RequestCookie method.
+message RequestCookieResponse {
+  // The payload of the cookie.
+  // May be empty if the cookie is not found.
+  bytes payload = 1;
+}
+
+
 // DisconnectPlayerRequest is the request for DisconnectPlayer method.
 message DisconnectPlayerRequest {
   // The player's username or ID to disconnect

pkg/edition/java/bossbar/bossbar.go

@@ -2,6 +2,8 @@
 package bossbar
 
 import (
+	"context"
+
 	"go.minekube.com/common/minecraft/component"
 	packet "go.minekube.com/gate/pkg/edition/java/proto/packet/bossbar"
 	"go.minekube.com/gate/pkg/edition/java/proto/packet/chat"
@@ -79,6 +81,7 @@ func RemoveAllViewers(b BossBar) {
 // Viewer is the interface for a boss bar viewer (e.g. a player).
 type Viewer interface {
 	ID() uuid.UUID
+	Context() context.Context
 	proto.PacketWriter
 }
 

pkg/edition/java/bossbar/internal.go

@@ -2,11 +2,12 @@ package bossbar
 
 import (
 	"context"
-	"go.minekube.com/gate/pkg/edition/java/proto/packet/chat"
 	"sync"
 
+	"go.minekube.com/gate/pkg/edition/java/proto/packet/chat"
+
 	"go.minekube.com/common/minecraft/component"
-	"go.minekube.com/gate/pkg/edition/java/internal/protoutil"
+	"go.minekube.com/gate/pkg/edition/java/internal/methods"
 	"go.minekube.com/gate/pkg/edition/java/proto/packet/bossbar"
 	"go.minekube.com/gate/pkg/edition/java/proto/version"
 	"go.minekube.com/gate/pkg/gate/proto"
@@ -78,17 +79,14 @@ func (b *bossBar) AddViewer(viewer Viewer) error {
 
 func newBarViewer(viewer Viewer, bar *bossBar) *barViewer {
 	removedCtx, cancel := context.WithCancel(context.Background())
-	if c, ok := viewer.(interface{ Context() context.Context }); ok {
-		viewerCtx := c.Context()
-		go func() {
-			defer cancel()
-			select {
-			case <-viewerCtx.Done():
-				_ = bar.RemoveViewer(viewer)
-			case <-removedCtx.Done(): // viewer removed by RemoveViewer method
-			}
-		}()
-	}
+	go func() {
+		defer cancel()
+		select {
+		case <-viewer.Context().Done():
+			_ = bar.RemoveViewer(viewer)
+		case <-removedCtx.Done(): // viewer removed by RemoveViewer method
+		}
+	}()
 	return &barViewer{
 		Viewer:  viewer,
 		ctx:     removedCtx,
@@ -252,7 +250,7 @@ func toSlice(m map[uuid.UUID]*barViewer) []Viewer {
 // isProtocolSupported returns true the viewer's protocol supports boss bar.
 func isProtocolSupported(viewer Viewer) bool {
 	// below 1.9 doesn't support boss bars
-	p, ok := protoutil.Protocol(viewer)
+	p, ok := methods.Protocol(viewer)
 	if !ok {
 		// assume supported
 		return true

pkg/edition/java/cookie/cookie.go

@@ -0,0 +1,77 @@
+package cookie
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/robinbraemer/event"
+	"go.minekube.com/common/minecraft/key"
+	"go.minekube.com/gate/pkg/edition/java/proto/packet/cookie"
+	"go.minekube.com/gate/pkg/edition/java/proto/state/states"
+	"go.minekube.com/gate/pkg/gate/proto"
+)
+
+var (
+	ErrUnsupportedClientProtocol = errors.New("player version must be at least 1.20.5 to use cookies")
+	ErrUnsupportedState          = fmt.Errorf("cookie can only be stored in %s or %s state", states.ConfigState, states.PlayState)
+)
+
+const (
+	MaxPayloadSize        = cookie.MaxPayloadSize
+	DefaultRequestTimeout = 10 * time.Second
+)
+
+// Cookie is cookie that can be sent and received from clients.
+//
+// Use Store to save a cookie on the client.
+// When the cookie is modified, Store must be called again to save the changes.
+//
+// The maximum size of a cookie is 5 kiB.
+type Cookie struct {
+	Key     key.Key
+	Payload []byte
+}
+
+// Client is a player that can store and send stored cookies.
+type Client interface {
+	proto.PacketWriter
+	Context() context.Context
+}
+
+// Store stores a cookie on the player's client.
+//
+// If the player's protocol is below 1.20.5, ErrUnsupportedClientProtocol is returned.
+// If the player's state is not states.ConfigState or states.PlayState, ErrUnsupportedState is returned.
+func Store(c Client, cookie *Cookie) error {
+	return store(c, cookie)
+}
+
+// Clear clears a stored cookie from the player's client.
+// This is a helper function that stores a cookie with an empty payload.
+//
+// If the player's protocol is below 1.20.5, ErrUnsupportedClientProtocol is returned.
+// If the player's state is not states.ConfigState or states.PlayState, ErrUnsupportedState is returned.
+func Clear(c Client, key key.Key) error {
+	return store(c, &Cookie{Key: key, Payload: nil})
+}
+
+// Request requests a stored cookie from the player's client by a given key.
+// This is a blocking operation and the context should be used to timeout the request.
+// The DefaultRequestTimeout always applies as a safety net.
+//
+// The event manager is used to listen for the cookie response event fired by Gate.
+// Use proxy.Event() to get the proxy's event manager.
+//
+// Request only subscribes to the cookie response event only until Request returns.
+func Request(ctx context.Context, c Client, key key.Key, eventMgr event.Manager) (*Cookie, error) {
+	return request(ctx, c, key, eventMgr)
+}
+
+// RequestAndForget works like Request but does not wait for a response.
+//
+// The cookie response event will still be fired by Gate and can be listened to in the event manager.
+func RequestAndForget(c Client, key key.Key) error {
+	return requestAndForget(c, key)
+}