Record Class RateLimitInfo

java.lang.Object

java.lang.Record

cloud.opencode.base.web.ratelimit.RateLimitInfo

public record RateLimitInfo(long limit, long remaining, long resetEpochSecond)
extends Record

Rate Limit Info - HTTP Rate Limiting Header Parser and Builder 限流信息 - HTTP 限流头部解析器和构建器

An immutable record representing rate limit information typically conveyed via HTTP response headers. Supports both parsing rate limit headers from responses and generating them for responses.

一个不可变记录，表示通常通过 HTTP 响应头部传递的限流信息。支持从响应中解析限流头部 以及为响应生成限流头部。

Standard Headers | 标准头部:

• X-RateLimit-Limit — Maximum requests allowed in the window - 窗口内允许的最大请求数
• X-RateLimit-Remaining — Remaining requests in the window - 窗口内剩余请求数
• X-RateLimit-Reset — Unix epoch second when the window resets - 窗口重置的 Unix 纪元秒
• Retry-After — Seconds until the client should retry - 客户端应重试的秒数

Usage Examples | 使用示例:

// Create rate limit info
RateLimitInfo info = RateLimitInfo.of(100, 42, Instant.now().plusSeconds(3600).getEpochSecond());

// Apply to response headers
HttpHeaders headers = HttpHeaders.of();
info.applyTo(headers);

// Parse from response headers
RateLimitInfo parsed = RateLimitInfo.fromHeaders(headers);
if (parsed != null && parsed.isExhausted()) {
    long waitSeconds = parsed.retryAfterSeconds();
}

Security | 安全性:

• Thread-safe: Yes (immutable record) - 是（不可变记录）
• Null-safe: Factory methods validate arguments - 工厂方法验证参数

Since:

JDK 25, opencode-base-web V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

• OpenCode.cloud

Field Summary

Fields

Modifier and Type	Field	Description
static final String	HEADER_LIMIT	X-RateLimit-Limit header name.
static final String	HEADER_REMAINING	X-RateLimit-Remaining header name.
static final String	HEADER_RESET	X-RateLimit-Reset header name (Unix epoch seconds).
static final String	HEADER_RETRY_AFTER	Retry-After header name (seconds).

Constructor Summary

Constructors

Constructor	Description
RateLimitInfo(long limit, long remaining, long resetEpochSecond)	Compact constructor with validation.

Method Summary

Modifier and Type	Method	Description
void	applyTo(HttpHeaders headers)	Applies rate limit headers to the given HttpHeaders.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
static RateLimitInfo	fromHeaders(HttpHeaders headers)	Parses rate limit information from HTTP response headers.
final int	hashCode()	Returns a hash code value for this object.
boolean	isExhausted()	Checks if the rate limit has been exhausted (no remaining requests).
long	limit()	Returns the value of the limit record component.
static RateLimitInfo	of(long limit, long remaining, long resetEpochSecond)	Creates a RateLimitInfo instance.
long	remaining()	Returns the value of the remaining record component.
long	resetEpochSecond()	Returns the value of the resetEpochSecond record component.
Instant	resetInstant()	Returns the reset time as an Instant.
long	retryAfterSeconds()	Calculates the number of seconds until the rate limit window resets.
final String	toString()	Returns a string representation of this record class.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

HEADER_LIMIT

public static final String HEADER_LIMIT

X-RateLimit-Limit header name.

See Also:

• Constant Field Values

HEADER_REMAINING

public static final String HEADER_REMAINING

X-RateLimit-Remaining header name.

See Also:

• Constant Field Values

HEADER_RESET

public static final String HEADER_RESET

X-RateLimit-Reset header name (Unix epoch seconds).

See Also:

• Constant Field Values

HEADER_RETRY_AFTER

public static final String HEADER_RETRY_AFTER

Retry-After header name (seconds).

See Also:

• Constant Field Values

Constructor Details

RateLimitInfo

public RateLimitInfo(long limit,
 long remaining,
 long resetEpochSecond)

Compact constructor with validation. 带验证的紧凑构造函数。

Throws:

IllegalArgumentException - if limit is negative, remaining is negative, or remaining exceeds limit - 如果 limit 或 remaining 为负数，或 remaining 超过 limit

Method Details

of

public static RateLimitInfo of(long limit,
 long remaining,
 long resetEpochSecond)

Creates a RateLimitInfo instance. 创建 RateLimitInfo 实例。

Parameters:

limit - the rate limit ceiling - 限流上限

remaining - the remaining requests in the current window - 当前窗口中剩余的请求数

resetEpochSecond - the Unix epoch second when the window resets - 窗口重置的 Unix 纪元秒

Returns:

a new RateLimitInfo - 新的 RateLimitInfo

fromHeaders

public static RateLimitInfo fromHeaders(HttpHeaders headers)

Parses rate limit information from HTTP response headers. 从 HTTP 响应头部解析限流信息。

Returns null if the required headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are not present or cannot be parsed as valid numbers.

如果所需头部不存在或无法解析为有效数字，则返回 null。

Parameters:

headers - the HTTP headers to parse - 要解析的 HTTP 头部

Returns:

the parsed RateLimitInfo or null - 解析的 RateLimitInfo 或 null

isExhausted

public boolean isExhausted()

Checks if the rate limit has been exhausted (no remaining requests). 检查限流是否已耗尽（没有剩余请求）。

Returns:

true if remaining is zero - 如果剩余为零返回 true

retryAfterSeconds

public long retryAfterSeconds()

Calculates the number of seconds until the rate limit window resets. 计算距离限流窗口重置的秒数。

Returns 0 if the reset time is in the past.

如果重置时间已过则返回 0。

Returns:

seconds until reset (non-negative) - 距离重置的秒数（非负）

resetInstant

public Instant resetInstant()

Returns the reset time as an Instant. 返回重置时间的 Instant。

Returns:

the reset Instant - 重置的 Instant

applyTo

public void applyTo(HttpHeaders headers)

Applies rate limit headers to the given HttpHeaders. 将限流头部应用到给定的 HttpHeaders。

Sets the standard rate limit headers and, if the limit is exhausted, also sets the Retry-After header.

设置标准限流头部，如果限流已耗尽，还会设置 Retry-After 头部。

Parameters:

headers - the headers to apply to - 要应用的头部

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with the compare method from their corresponding wrapper classes.

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

limit

public long limit()

Returns the value of the limit record component.

Returns:

the value of the limit record component

remaining

public long remaining()

Returns the value of the remaining record component.

Returns:

the value of the remaining record component

resetEpochSecond

public long resetEpochSecond()

Returns the value of the resetEpochSecond record component.

Returns:

the value of the resetEpochSecond record component