(** Chunk file management for partial downloads and resumable transfers

    This module manages partial cache entries (chunks) that can be combined
    to form complete files. Chunks enable resumable downloads and efficient
    caching of large files by storing byte ranges independently.

    Each chunk is stored as a separate file with range information encoded
    in its filename, allowing the cache to resume interrupted downloads
    and serve partial content requests efficiently. *)

(** Information about a chunk file *)
type t

(** Get the key *)
val key : t -> string

(** Get the hash *)
val hash : t -> string

(** Get the range *)
val range : t -> Range.t

(** Get the path *)
val path : t -> Eio.Fs.dir_ty Eio.Path.t

(** Get the flags *)
val flags : t -> Flags.t

(** Get the TTL *)
val ttl : t -> float option

(** Parse a chunk from a filename and path *)
val parse : path:Eio.Fs.dir_ty Eio.Path.t -> filename:string -> t option

(** Generate a chunk filename *)
val make_filename : hash:string -> range:Range.t ->
                   ?ttl:float -> ?flags:Flags.t -> unit -> string

(** Find all chunks for a key in a directory structure *)
val find_chunks : base_dir:Eio.Fs.dir_ty Eio.Path.t ->
                 key:string -> t list

(** Check if chunks form a complete sequence *)
val is_complete_sequence : t list -> total_size:int64 -> bool

(** Get missing ranges from a list of chunks *)
val missing_ranges : t list -> total_size:int64 -> Range.t list

(** Sort chunks by range start position *)
val sort_by_range : t list -> t list

(** Pretty printer *)
val pp : Format.formatter -> t -> unit