Class RangeUtils

java.lang.Object

io.leandev.appfuse.file.RangeUtils

public final class RangeUtils
extends Object

HTTP Range 請求處理工具

支援 RFC 7233 定義的 Range 請求格式，用於實現斷點續傳與部分內容下載。

支援的格式

• bytes=0-1000 - 從 0 到 1000 bytes
• bytes=1000- - 從 1000 到檔案結尾
• bytes=-500 - 最後 500 bytes

使用範例

switch (RangeUtils.evaluate(rangeHeader, fileSize)) {
    case RangeRequest.Absent absent -> ...;                     // 200 完整內容
    case RangeRequest.Satisfiable(ByteRange range) -> ...;      // 206，只讀取該區段
    case RangeRequest.Unsatisfiable(long size) -> ...;          // 416，Content-Range: bytes */size
}

See Also:

• FileResponseBuilder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	RangeUtils.ByteRange	位元組範圍
static interface	RangeUtils.RangeRequest	Range header 的評估結果

Method Summary

Modifier and Type	Method	Description
static RangeUtils.RangeRequest	evaluate(String rangeHeader, long size)	評估 HTTP Range header（RFC 9110 §14）
static boolean	isRangeRequest(String rangeHeader)	檢查是否為有效的 Range 請求
static Optional<RangeUtils.ByteRange>	parseRange(String rangeHeader, long fileSize)	Deprecated. 無法滿足與格式錯誤都回傳 empty，無法區分 416 與完整內容；改用 evaluate(String, long)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

evaluate

public static RangeUtils.RangeRequest evaluate(String rangeHeader,
 long size)

評估 HTTP Range header（RFC 9110 §14）

分兩步：先在十進位字串上檢查語法（last 小於 first 的 range 無效；數字不先轉成 long，避免溢位）， 語法合法的單一 range 才判斷可滿足性。

• 缺少、單位不是 bytes、語法錯誤、多個 range → RangeUtils.RangeRequest.Absent
• first 小於檔案大小，或 suffix 長度大於 0 且檔案非空 → RangeUtils.RangeRequest.Satisfiable（last 截到結尾）
• 其餘語法合法者（first 超過結尾、bytes=-0、空檔案）→ RangeUtils.RangeRequest.Unsatisfiable

Parameters:

rangeHeader - HTTP Range header 值，可為 null

size - 檔案大小（不可為負）

Returns:

評估結果

parseRange

@Deprecated(since="4.0.0")
public static Optional<RangeUtils.ByteRange> parseRange(String rangeHeader,
 long fileSize)

Deprecated.

無法滿足與格式錯誤都回傳 empty，無法區分 416 與完整內容；改用 evaluate(String, long)

解析 HTTP Range header

根據 RFC 7233 規範解析 Range header，支援以下格式：

• bytes=0-1000 - 絕對範圍
• bytes=1000- - 從指定位置到結尾
• bytes=-500 - 最後 N bytes（suffix range）

Parameters:

rangeHeader - HTTP Range header 值（如 "bytes=0-1000"）

fileSize - 檔案總大小

Returns:

解析後的範圍，若格式無效則回傳 empty

isRangeRequest

public static boolean isRangeRequest(String rangeHeader)

檢查是否為有效的 Range 請求

Parameters:

rangeHeader - HTTP Range header 值

Returns:

是否為有效的 Range 請求格式