nebius.aio.token.options

module documentation

(source)

Request option keys used by the token renewal machinery.

This module defines string constants that are used as keys in the options mapping passed to per-request Receiver.fetch calls and similar APIs. The values associated with these keys are interpreted by the renewal and exchangeable bearers to control retry and renewal behaviour.

General conventions

Boolean flags: A present key with a nonempty value enables the option. The exact string value has no effect.
Numeric overrides: some options accept numeric values encoded as strings (for example OPTION_MAX_RETRIES and OPTION_RENEW_REQUEST_TIMEOUT). These are parsed using int or float respectively; invalid values are logged and ignored, falling back to implementation defaults.

Options

OPTION_MAX_RETRIES

Key: "max_fetch_token_retries"

This key changes the maximum retrieval retries for the current receiver. Its value must be a decimal integer string, such as "3". An invalid value has no effect. The usual default is 2.

OPTION_RENEW_REQUIRED

Key: "token_renew_required"

This flag forces renewal of a fresh cached token. A nonempty value enables the option. Examples use "1" or "true".

OPTION_RENEW_SYNCHRONOUS

Key: "token_renew_synchronous"

When present and non-empty this flag requests a synchronous renewal for the current fetch operation. In synchronous mode the caller waits for a fresh token to be retrieved before Receiver.fetch returns (subject to the usual timeout). Note that synchronous requests may also suppress triggering a background renewal from the receiver's retry logic.

OPTION_REPORT_ERROR

Key: "token_renew_report_error"

When set, Receiver.fetch raises renewal errors. Background retry logic does not hide these errors. Use this option to report renewal failures immediately.

OPTION_RENEW_REQUEST_TIMEOUT

Key: "token_renew_request_timeout"

Numeric override controlling the timeout (in seconds) used for a synchronous renewal request. The value must be a floating-point number encoded as a string (for example "2.5"). If the value cannot be parsed as a float the option is ignored and the bearer's configured default timeout is used (typically 5 seconds).

Examples

Typical usage when requesting a synchronous renewal with a short timeout:

options = {
        OPTION_RENEW_REQUIRED: "1",
        OPTION_RENEW_SYNCHRONOUS: "1",
        OPTION_RENEW_REQUEST_TIMEOUT: "0.2",
}

Override the maximum number of retries for a specific fetch:

options = {
        OPTION_MAX_RETRIES: "5",
}

Notes

Implementations that read these options generally follow the patterns used in nebius.aio.token.renewable and nebius.aio.token.exchangeable: boolean flags are tested by checking for a non-empty value, while numeric overrides are parsed and validated. Invalid numeric values are logged and ignored.

Constant	`OPTION_MAX_RETRIES`	Override the maximum number of token fetch retries for a single receiver.
Constant	`OPTION_RENEW_REQUEST_TIMEOUT`	Floating-point timeout (in seconds) used for synchronous renewal requests.
Constant	`OPTION_RENEW_REQUIRED`	Boolean-like flag that forces a token renewal.
Constant	`OPTION_RENEW_SYNCHRONOUS`	Request a synchronous renewal for the current fetch.
Constant	`OPTION_REPORT_ERROR`	When set, report renewal errors to the caller.

OPTION_MAX_RETRIES: str = (source) ¶

Override the maximum number of token fetch retries for a single receiver.

When provided in a request options mapping the value must be a decimal integer encoded as a string (for example "3"). If the value cannot be parsed as an integer the option is ignored and the receiver's configured default is used.

Value

'max_fetch_token_retries'

OPTION_RENEW_REQUEST_TIMEOUT: str = (source) ¶

Floating-point timeout (in seconds) used for synchronous renewal requests.

The value is parsed using float (for example "2.5"). Invalid values are ignored and the bearer's configured default is used.

Value

'token_renew_request_timeout'

OPTION_RENEW_REQUIRED: str = (source) ¶

Boolean-like flag that forces a token renewal.

Any non-empty string value (commonly "1" or "true") enables the behaviour; presence of the key signals that the cached token should be refreshed even if it would normally be considered fresh.

Value

'token_renew_required'

OPTION_RENEW_SYNCHRONOUS: str = (source) ¶

Request a synchronous renewal for the current fetch.

When this key is present with a non-empty value the fetch operation will block until a new token has been retrieved (subject to the fetch timeout and the optional OPTION_RENEW_REQUEST_TIMEOUT override).

Value

'token_renew_synchronous'

OPTION_REPORT_ERROR: str = (source) ¶

When set, report renewal errors to the caller.

If present and non-empty renewal errors are propagated to the caller of Receiver.fetch (instead of being handled by background retry logic). This is useful for callers that need immediate visibility of failures.

Value

'token_renew_report_error'