agones.dev/agones@v1.54.0/pkg/processor/doc.go (about)

     1  // Copyright 2025 Google LLC All Rights Reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package processor provides client functionality for the Agones allocation processor system
    16  //
    17  // The allocation processor system enables batched game server allocation requests
    18  // This package contains the client implementation that connects to the processor service
    19  // batches allocation requests, and handles the stream-based communication protocol
    20  //
    21  // Key components:
    22  // - Client: Manages connection lifecycle and request batching
    23  // - Config: Configuration for processor client behavior
    24  // - Batch handling: Accumulates requests and sends them in batches to the processor
    25  //
    26  // The client establishes a bidirectional gRPC stream with the processor service,
    27  // registers itself, and then handles pull requests (to send batched allocations)
    28  // and batch responses (containing allocation results)
    29  //
    30  // Flow diagram:
    31  //
    32  //	┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
    33  //	│     Client      │    │  Processor Client   │    │  Processor Server   │
    34  //	│  (Allocator/    │    │   (this package)    │    │                     │
    35  //	│   Extension)    │    │                     │    │                     │
    36  //	└─────────────────┘    └─────────────────────┘    └─────────────────────┘
    37  //	         │                        │                          │
    38  //	         │                        │ 1. Connect & Register    │
    39  //	         │                        │    (bidirectional stream)│
    40  //	         │                        ├──────────────────────────►
    41  //	         │                        │                          │
    42  //	         │ 2. Allocate(request)   │                          │
    43  //	         ├────────────────────────►                          │
    44  //	         │                        │                          │
    45  //	         │                        │ 3. Add to hotBatch       │
    46  //	         │                        │    (accumulate)          │
    47  //	         │                        │                          │
    48  //	         │                        │ 4. Pull Request          │
    49  //	         │                        │    (to all clients)      │
    50  //	         │                        ◄──────────────────────────┤
    51  //	         │                        │ 5. Send BatchRequest     │
    52  //	         │                        │    (hotBatch)            │
    53  //	         │                        ├──────────────────────────►
    54  //	         │                        │                          │
    55  //	         │                        │                          │ 6. Process
    56  //	         │                        │                          │    allocations
    57  //	         │                        │                          │
    58  //	         │                        │ 7. BatchResponse         │
    59  //	         │                        │    (results)             │
    60  //	         │                        ◄──────────────────────────┤
    61  //	         │ 8. Return result       │                          │
    62  //	         ◄────────────────────────┤                          │
    63  //	         │                        │                          │
    64  //
    65  //	Note: Multiple Processor Clients can connect to one Processor Server
    66  //	      The server sends pull requests to all connected clients
    67  //
    68  //	Legend:
    69  //	- Client: Makes allocation requests (allocator, extensions, etc.)
    70  //	- Processor Client: Batches requests and manages communication
    71  //	- Processor Server: Processes batched allocations from multiple clients
    72  //	- Pull Request: Server asks all connected clients for pending requests
    73  //	- BatchRequest: Client sends accumulated allocation requests
    74  //	- BatchResponse: Server returns allocation results
    75  package processor