///|
/// Encodes and decodes one third-party HDF5 filter for dataset chunks and
/// fractal-heap metadata.
///
/// HDF5 applies filters in reverse pipeline order. `data` is the payload at
/// this stage, `element_size` is the dataset element width (zero for metadata
/// heap blocks), and `expected_size` is the decoded byte count. A decoder must
/// return exactly `expected_size` bytes. Implementations that only read files
/// may omit `encode`; trying to write through such a filter raises
/// `UnsupportedFeature`.
pub(open) trait Hdf5CustomFilter {
  fn id(Self) -> Int32
  fn name(Self) -> String = _
  fn decode(
    Self,
    data : Bytes,
    parameters : Array[UInt32],
    element_size : Int32,
    expected_size : Int32,
  ) -> Bytes raise Hdf5Error
  fn encode(
    Self,
    data : Bytes,
    parameters : Array[UInt32],
    element_size : Int32,
    expected_size : Int32,
  ) -> Bytes raise Hdf5Error = _
}

///|
impl Hdf5CustomFilter with fn name(self) {
  "custom-filter-" + self.id().to_string()
}

///|
impl Hdf5CustomFilter with fn encode(
  self,
  data,
  parameters,
  element_size,
  expected_size,
) {
  self |> ignore
  data |> ignore
  parameters |> ignore
  element_size |> ignore
  expected_size |> ignore
  raise UnsupportedFeature(
    "custom filter " + self.id().to_string() + " does not provide an encoder",
  )
}

///|
fn validate_custom_filter_id(id : Int32) -> Unit raise Hdf5Error {
  guard id >= 0 && id <= 65535 else {
    raise InvalidArgument("custom filter ID must fit in an HDF5 uint16")
  }
  guard id != 1 && id != 2 && id != 3 && id != 6 else {
    raise InvalidArgument("custom filters cannot replace built-in filter IDs")
  }
}

///|
fn validate_custom_filter(filter : &Hdf5CustomFilter) -> Unit raise Hdf5Error {
  let id = filter.id()
  validate_custom_filter_id(id)
  if id >= 256 {
    guard @utf8.encode(filter.name()).length() <= 65535 else {
      raise InvalidArgument("custom filter name is too long")
    }
  }
}

///|
fn register_custom_filter(
  filters : Array[&Hdf5CustomFilter],
  filter : &Hdf5CustomFilter,
) -> Unit raise Hdf5Error {
  validate_custom_filter(filter)
  let id = filter.id()
  guard filters.search_by(existing => existing.id() == id) is None else {
    raise InvalidArgument(
      "custom filter is already registered: " + id.to_string(),
    )
  }
  filters.push(filter)
}

///|
fn find_custom_filter(
  filters : Array[&Hdf5CustomFilter],
  id : Int32,
) -> &Hdf5CustomFilter raise Hdf5Error {
  match filters.search_by(filter => filter.id() == id) {
    Some(index) => filters[index]
    None =>
      raise InvalidArgument(
        "custom filter is not registered: " + id.to_string(),
      )
  }
}