Update Docs: CountersAndLists to Beta (googleforgames#3810)

* Update Docs: CountersAndLists to Beta

* fix lint

* CL under spec in gs.yaml gsa.yaml

* align gsa.yaml

* review changes

* uncomment lists capacity

* tweak in yaml and md files

* revert gs.md

* CL beta in gs.md

---------

Co-authored-by: Zach Loafman <[email protected]>

examples/fleet.yaml

@@ -89,25 +89,25 @@ spec:
         #  - "Error" The SDK server will only output error messages
         logLevel: Info
       #
-      # [Stage:Alpha]
+      # [Stage:Beta]
       # [FeatureFlag:CountsAndLists]
       # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features.
-      # Commented out since Alpha, and disabled by default
-      # counters:
-      #   players:
-      #     count: 9
-      #     capacity: 10
-      #   sessions:
-      #     count:  # Count and/or capacity must be listed (but may be nil) otherwise the counter will by dropped by the CRD schema.
-      # lists:
-      #   players:
-      #     capacity:  # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema.
-      #   rooms:
-      #     capacity: 5
-      #     values:
-      #       - room1
-      #       - room2
-      #       - room3
+      # Now in Beta, and enabled by default
+      counters:
+        players:
+          count: 9
+          capacity: 10
+        sessions:
+          count:  # Count and/or capacity must be listed (but may be nil) otherwise the counter will by dropped by the CRD schema.
+      lists:
+        players:
+          capacity:  # Capacity and/or values must be listed (but may be nil) otherwise the list will be dropped by the CRD schema.
+        rooms:
+          capacity: 5
+          values:
+            - room1
+            - room2
+            - room3
       #
       # The GameServer's Pod template
       template:

examples/gameserver.yaml

@@ -91,25 +91,25 @@ spec:
   #  # set this GameServer's initial player capacity
   #   initialCapacity: 10
   #
-  # [Stage:Alpha]
+  # [Stage:Beta]
   # [FeatureFlag:CountsAndLists]
   # Counts and Lists provides the configuration for generic (player, room, session, etc.) tracking features.
-  # Commented out since Alpha, and disabled by default
-  # counters: # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time.
-  #   games: # arbitrary key.
-  #     count: 1 # initial value.
-  #     capacity: 100 # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details.
-  #   sessions:
-  #     count: 1
-  # lists: # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time.
-  #   players: # an empty list, with a capacity set to 10.
-  #     capacity: 10  # capacity value, defaults to 1000.
-  #   rooms:
-  #     capacity: 333
-  #     values: # initial set of values in a list.
-  #       - room1
-  #       - room2
-  #       - room3
+  # Now in Beta, and enabled by default
+  counters:  # counters are int64 counters that can be incremented and decremented by set amounts. Keys must be declared at GameServer creation time.
+    games:  # arbitrary key.
+      count: 1  # initial value.
+      capacity: 100  # (Optional) Defaults to 1000 and setting capacity to max(int64) may lead to issues and is not recommended. See GitHub issue https://github.com/googleforgames/agones/issues/3636 for more details.
+    sessions:
+      count: 1
+  lists:  # lists are lists of values stored against this GameServer that can be added and deleted from. Keys must be declared at GameServer creation time.
+    players:  # an empty list, with a capacity set to 10.
+      capacity: 10  # capacity value, defaults to 1000.
+    rooms:
+      capacity: 333
+      values:  # initial set of values in a list.
+        - room1
+        - room2
+        - room3
   #
   # Pod template configuration
   template:

examples/gameserverallocation.yaml

@@ -28,15 +28,14 @@ metadata:
   name: allocation-example
 spec:
   # GameServer selector from which to choose GameServers from.
-  # GameServers still have the hard requirement to be `Ready` to be allocated from
-  # however we can also make available `matchExpressions` for even greater
-  # flexibility.
+  # GameServers still have the hard requirement to be `Ready` to be allocated from.
+  # However, we can also make available `matchExpressions` for even greater flexibility.
   # Below is an example of a GameServer allocated against a given fleet.
   # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details
   # The selectors is an ordered list of allocations set.
   # If the first selector is not matched, the selection attempts the second selector, and so on.
   # This is useful for things like smoke testing of new game servers.
-  # This also support `matchExpressions`
+  # This also supports `matchExpressions`
   selectors:
     - matchLabels:
         agones.dev/fleet: green-fleet
@@ -50,19 +49,19 @@ spec:
       # via Allocation. Defaults to "Ready". The only other option is "Allocated", which can be used in conjunction with
       # label/annotation/player selectors to retrieve an already Allocated GameServer.
       gameServerState: Ready
-      # [Stage:Alpha]
+      # [Stage:Beta]
       # [FeatureFlag:CountsAndLists]
-      # counters: # selector for counter current values of a GameServer count
-      #   rooms:
-      #     minCount: 1 # minimum value. Defaults to 0.
-      #     maxCount: 5 # maximum value. Defaults to max(int64)
-      #     minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0.
-      #     maxAvailable: 10 # maximum available (current capacity - current count) Defaults to max(int64)
-      # lists:
-      #   players:
-      #     containsValue: "x6k8z" # only match GameServers who has this value in the list. Defaults to "", which is all.
-      #     minAvailable: 1 # minimum available (current capacity - current count). Defaults to 0.
-      #     maxAvailable: 10 # maximum available (current capacity - current count) Defaults to 0, which translates to max(int64)
+      counters:  # selector for counter current values of a GameServer count
+        rooms:
+          minCount: 1  # minimum value. Defaults to 0.
+          maxCount: 5  # maximum value. Defaults to max(int64)
+          minAvailable: 1  # minimum available (current capacity - current count). Defaults to 0.
+          maxAvailable: 10  # maximum available (current capacity - current count) Defaults to max(int64)
+      lists:
+        players:
+          containsValue: "x6k8z"  # only match GameServers who has this value in the list. Defaults to "", which is all.
+          minAvailable: 1  # minimum available (current capacity - current count). Defaults to 0.
+          maxAvailable: 10  # maximum available (current capacity - current count) Defaults to 0, which translates to max(int64)
       #
       # [Stage:Alpha]
       # [FeatureFlag:PlayerAllocationFilter]
@@ -86,7 +85,7 @@ spec:
     annotations:
       map: garden22
   # yamllint disable rule:comments-indentation rule:line-length
-  # [Stage: Alpha]
+  # [Stage: Beta]
   # [FeatureFlag:CountsAndLists]
   # `Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`.
   #
@@ -98,22 +97,22 @@ spec:
   # For `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the
   # order that `GameServers` will be allocated by.
   # Optional.
-  # priorities:
-  # - type: Counter  # Whether a Counter or a List.
-  #   key: rooms  # The name of the Counter or List.
-  #   order: Ascending  # "Ascending" lists smaller available capacity first.
-  # [Stage:Alpha]
+  priorities:
+    - type: Counter  # Whether a Counter or a List.
+      key: rooms  # The name of the Counter or List.
+      order: Ascending  # "Ascending" lists smaller available capacity first.
+  # [Stage:Beta]
   # [FeatureFlag:CountsAndLists]
   # Counter actions to perform during allocation. Optional.
-  # counters:
-  #   rooms:
-  #     action: Increment # Either "Increment" or "Decrement" the Counter’s Count.
-  #     amount: 1 # Amount is the amount to increment or decrement the Count. Must be a positive integer.
-  #     capacity: 5 # Amount to update the maximum capacity of the Counter to this number. Min 0, Max int64.
+  counters:
+    rooms:
+      action: Increment  # Either "Increment" or "Decrement" the Counter’s Count.
+      amount: 1  # Amount is the amount to increment or decrement the Count. Must be a positive integer.
+      capacity: 5  # Amount to update the maximum capacity of the Counter to this number. Min 0, Max int64.
   # List actions to perform during allocation. Optional.
-  # lists:
-  #   players:
-  #     addValues: # appends values to a List’s Values array. Any duplicate values will be ignored
-  #       - x7un
-  #       - 8inz
-  #     capacity: 40 # Updates the maximum capacity of the Counter to this number. Min 0, Max 1000.
+  lists:
+    players:
+      addValues:  # appends values to a List’s Values array. Any duplicate values will be ignored
+        - x7un
+        - 8inz
+      capacity: 40  # Updates the maximum capacity of the Counter to this number. Min 0, Max 1000.

site/content/en/docs/Guides/Client SDKs/_index.md

@@ -52,6 +52,7 @@ The SDKs will automatically discover and connect to the gRPC port specified in t
 If your game server requires using a REST client, it is advised to use the port from the environment variable,
 otherwise your game server will not be able to contact the SDK server if it is configured to use a non-default port.
 
+{{% feature expiryVersion="1.41.0" %}}
 ## Function Reference
 
 While each of the SDKs are canonical to their languages, they all have the following
@@ -80,6 +81,37 @@ Functions which changes GameServer state or settings are:
 14. Alpha().AppendListValue()
 15. Alpha().DeleteListValue()
 16. Alpha().SetListCapacity()
+{{% /feature %}}
+{{% feature publishVersion="1.41.0" %}}
+## Function Reference
+
+While each of the SDKs are canonical to their languages, they all have the following
+functions that implement the core responsibilities of the SDK.
+
+For language specific documentation, have a look at the respective source (linked above), 
+and the {{< ghlink href="examples" >}}examples{{< /ghlink >}}.
+
+Calling any of state changing functions mentioned below does not guarantee that GameServer Custom Resource object would actually change its state right after the call. For instance, it could be moved to the `Shutdown` state elsewhere (for example, when a fleet scales down), which leads to no changes in `GameServer` object. You can verify the result of this call by waiting for the desired state in a callback to WatchGameServer() function.
+
+Functions which changes GameServer state or settings are:
+
+1. Ready()
+2. Shutdown()
+3. SetLabel()
+4. SetAnnotation()
+5. Allocate()
+6. Reserve()
+7. Alpha().SetCapacity()
+8. Alpha().PlayerConnect()
+9. Alpha().PlayerDisconnect()
+10. Beta().SetCounterCount()
+11. Beta().IncrementCounter()
+12. Beta().DecrementCounter()
+13. Beta().SetCounterCapacity()
+14. Beta().AppendListValue()
+15. Beta().DeleteListValue()
+16. Beta().SetListCapacity()
+{{% /feature %}}
 
 ### Lifecycle Management
 
@@ -230,7 +262,12 @@ observable through the Kubernetes API.
 
 ### Counters And Lists
 
+{{% feature expiryVersion="1.41.0" %}}
 {{< alpha title="Counters And Lists" gate="CountsAndLists" >}}
+{{% /feature %}}
+{{% feature publishVersion="1.41.0" %}}
+{{< beta title="Counters And Lists" gate="CountsAndLists" >}}
+{{% /feature %}}
 
 The `Counters` and `Lists` features in the SDK offer a flexible configuration for tracking various entities like 
 players, rooms, and sessions.
@@ -259,6 +296,7 @@ to the capacity of that Counter or List.
 
 {{% /alert %}}
 
+{{% feature expiryVersion="1.41.0" %}}
 #### Counters
 
 All functions will return an error if the specified `key` is not predefined in the 
@@ -343,6 +381,93 @@ Convenience function, which retrieves the length of the results of [`Alpha().Get
 
 [gameserverspec]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}}
 [gameserverstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerStatus" >}}
+{{% /feature %}}
+{{% feature publishVersion="1.41.0" %}}
+#### Counters
+
+All functions will return an error if the specified `key` is not predefined in the 
+[`GameServer.Spec.Counters`][gameserverspec] resource configuration.
+
+**Note:** For Counters, the default setting for the capacity is preset to 1000. It is recommended to avoid configuring the capacity to max(int64), as doing so could cause problems with [JSON Patch operations](https://github.com/googleforgames/agones/issues/3636).
+
+##### Beta().GetCounterCount(key)
+
+This function retrieves either the [`GameServer.Status.Counters[key].Count`][gameserverstatus] or the SDK awaiting-batch
+value for a given key, whichever is most up to date.
+
+##### Beta().SetCounterCount(key, amount)
+
+This function sets the value of [`GameServer.Status.Counters[key].Count`][gameserverstatus] for the given key to the
+passed in amount. This operation overwrites any previous values and the new value cannot exceed the Counter's capacity.
+
+##### Beta().IncrementCounter(key, amount)
+
+This function increments [`GameServer.Status.Counters[key].Count`][gameserverstatus] for the given key by the passed in
+non-negative amount. The function returns an error if the Counter is already at capacity (at time of operation),
+indicating no increment will occur.
+
+##### Beta().DecrementCounter(key, amount)
+
+This function decreases [`GameServer.Status.Counters[key].Count`][gameserverstatus] for the given key by the passed in
+non-negative amount. It returns an error if the Counter's count is already at zero.
+
+##### Beta().SetCounterCapacity(key, amount)
+
+This function sets the maximum [`GameServer.Status.Counters[key].Capacity`][gameserverstatus] for the given key by the
+passed in non-negative amount. A capacity value of 0 indicates no capacity limit.
+
+##### Beta().GetCounterCapacity(key)
+
+This function retrieves either the [`GameServer.Status.Counters[key].Capacity`][gameserverstatus] or the SDK
+awaiting-batch value for the given key, whichever is most up to date.
+
+#### Lists
+
+All functions will return an error if the specified `key` is not predefined in the 
+[`GameServer.Spec.Lists`][gameserverspec] resource configuration.
+
+##### Beta().AppendListValue(key, value)
+
+This function appends the specified string value to the List
+in [`GameServer.Status.Lists[key].Values`][gameserverstatus].
+
+An error is returned if the string already exists in the list or if the list is at capacity.
+
+##### Beta().DeleteListValue(key, value)
+
+This function removes the specified string value from the List
+in [`GameServer.Status.Lists[key].Values`][gameserverstatus].
+
+An error is returned if the string does not exist in the list.
+
+##### Beta().SetListCapacity(key, amount)
+
+This function sets the maximum capacity for the List at [`GameServer.Status.Lists[key].Capacity`][gameserverstatus].
+
+The capacity value is required to be between 0 and 1000.
+
+##### Beta().GetListCapacity(key)
+
+This function retrieves either the [`GameServer.Status.Lists[key].Capacity`][gameserverstatus] or the SDK
+awaiting-batch value for the given key, whichever is most up to date.
+
+##### Beta().GetListValues(key)
+
+This function retrieves either the [`GameServer.Status.Lists[key].Values`][gameserverstatus] or the SDK
+awaiting-batch values array for the given key, whichever is most up to date.
+
+##### Beta().ListContains(key, value)
+
+Convenience function, which returns if the specific string value exists in the results
+of [`Beta().GetListValues(key)`](#betagetlistvalueskey).
+
+##### Beta().GetListLength(key)
+
+Convenience function, which retrieves the length of the results of [`Beta().GetListValues(key)`](#betagetlistvalueskey).
+
+[gameserverspec]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}}
+[gameserverstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerStatus" >}}
+{{% /feature %}}
 
 ### Player Tracking