trpc.group/trpc-go/trpc-go@v1.0.3/docs/user_guide/timeout_control.md (about)

     1  English | [中文](timeout_control.zh_CN.md)
     2  
     3  # tRPC-Go Timeout Control
     4  
     5  ## Introduction
     6  
     7  When making RPC requests, the framework sets a timeout for waiting for the response. If the specified time is exceeded, the client call will immediately return a timeout failure.
     8  
     9  Timeouts are divided into three configurations to provide finer-grained control over timeouts:
    10  
    11  - `Fulllink Timeout`: Upstream callers specify the maximum allowed time for the entire request through protocol fields. This means that the upstream caller requests that the response be delivered within a specific time frame. Any response received after this time is considered meaningless. This is illustrated in the diagram below, where A calls B with a `Fulllink Timeout`.
    12  
    13  - `Message Timeout`: This is the maximum timeout a current service is configured to spend processing a request from receiving the request message to sending the response data. This is a mechanism for the current service to control its resource utilization. It's depicted as the `Message Timeout` within service B in the diagram.
    14  
    15  - `Calling Timeout`: This is the maximum timeout for each RPC request when calling downstream services. For example, in the diagram, when B calls C, it sets a `Calling Timeout`. Typically, a server may involves multiple consecutive RPC calls, as shown when B calls C and then sequentially calls D and E. The `Calling Timeout` controls the timeout for each individual RPC call.
    16  
    17  ![ 'timeout_control.png'](/.resources/user_guide/timeout_control/timeout_control.png)
    18  
    19  When making an RPC call, framework will calculate the actual timeout for that specific call. The actual timeout is the minimum of the three timeout configurations mentioned above. The calculation process is as follows:
    20  
    21  - First, calculate the minimum of the `Fulllink Timeout` and `Message Timeout`. For example, if the `Fulllink Timeout` is 2 seconds and the `Message Timeout` is 1 second, then the `maximum allowed processing time for the current message` is 1 second.
    22  
    23  - When making an RPC call, calculate the minimum of the `maximum allowed processing time for the current message` and the `Calling Timeout` for that specific call. For example, if B->C sets a `Calling Timeout` of 5 seconds, then the actual timeout for B calling C is still 1 second. If B->C sets a `Calling Timeout` of 500 milliseconds, then the actual timeout for B calling C is 500 milliseconds. In this case, the value of 500 milliseconds is also passed to C via protocol fields, and from C's perspective, it becomes its `Fulllink Timeout`. The `Fulllink Timeout` time is passed down the entire RPC call chain, gradually decreasing until it reaches 0, preventing the possibility of infinite loops in calls.
    24  
    25  - Since each RPC call consumes some time, the `maximum allowed processing time for the current message` needs to be continuously updated in real-time to account for the remaining time. For example, if B calling C actually takes 200 milliseconds, then the `maximum allowed processing time for the current message` is reduced to 800 milliseconds. When making B->D call, it's necessary to calculate the minimum of the `maximum allowed processing time for the current message` and the `Calling Timeout` for B->D. For example, if B->D sets a `Calling Timeout` of 1 second, the effective timeout for this call is still 800 milliseconds.
    26  
    27  ## Implementation
    28  
    29  tRPC-Go's timeout control is implemented using the `Context`.
    30  
    31  `Context` is the first parameter for all RPC interfaces, allowing you to set timeouts and cancellations. Therefore, to make timeout control effective, all RPC calls must carry the `Context` of the request entry. **It's important to note that timeouts can only be controlled through the `Context`**.
    32  
    33  `Context` can only control the timeout of each individual call and cannot control the termination of goroutines. If your business code blocks without considering the `Context` (e.g., using `time.Sleep`), timeout control won't be effective, and the goroutine will be blocked indefinitely.
    34  
    35  When the Server receives a request, it calculates the `maximum allowed processing time for the current message`, sets a timeout using `context.WithTimeout`, and cancels the current `Context` when the business processing function is complete. Therefore, if you create goroutines to execute asynchronous logic, you must not use the entry request's `Context`. Instead, use a new `Context` such as `trpc.BackgroundContext()`.
    36  
    37  ## Detailed Configuration
    38  
    39  tRPC-Go's timeout control is specified entirely through configuration files.
    40  
    41  **Note**: The following settings are all specific to the current service's timeout configuration, which corresponds to server B in the preceding diagram.
    42  
    43  ### Fulllink Timeout
    44  
    45  By default, timeouts are passed down from the source service through protocol fields, and you can configure whether to inherit them or not. `Fulllink Timeout` is determined by the upstream client caller, and trpc Client by default sets the actual RPC timeout to the `Fulllink Timeout`.
    46  
    47  ```yaml
    48  server:
    49    service:
    50      - name: trpc.app.server.service
    51        disable_request_timeout: true  # Default is false, which means the timeout inherits from the upstream service. Set to true to disable inheriting timeout values passed from the upstream service.
    52  ```
    53  
    54  If you wish to completely disable timeouts, you can configure this value.
    55  
    56  ### Message Timeout
    57  
    58  Each service can configure the maximum message processing timeout for all incoming requests when starting up.
    59  
    60  If your business code blocks without considering the `Context` (e.g., using `time.Sleep`), timeout control won't be effective, and the processing goroutine won't terminate immediately.
    61  
    62  ```yaml
    63  server:
    64    service:
    65      - name: trpc.app.server.service
    66        timeout: 1000  # In milliseconds, each incoming request allows a maximum execution time of 1000ms. Be mindful of distributing timeout times for all serial RPC calls within the current request. Default is 0, indicating no timeout is set.
    67  ```
    68  
    69  ### Calling Timeout
    70  
    71  Each RPC call can configure the maximum timeout for the current request. If your code sets the `WithTimeout` option, the code configuration takes precedence. However, for flexibility, it's recommended to specify the calling timeout directly through the configuration file.
    72  
    73  ```yaml
    74  client:
    75    service:
    76      - name: trpc.app.server.service  # Downstream service name
    77        timeout: 500  # In milliseconds, each initiated request allows a maximum timeout of 500ms. Default is 0, indicating no timeout is set, meaning it will wait indefinitely.
    78  ```