///|
priv struct EditableLink {
link : GroupLink
creation_order : UInt64
}
///|
fn validate_editable_link_name(name : String) -> Unit raise Hdf5Error {
let encoded = @utf8.encode(name)
guard encoded.length() > 0 && encoded.length() <= 65535 else {
raise InvalidArgument("link name is empty or too long")
}
guard name != "." && name != ".." && !name.contains("/") else {
raise InvalidArgument("link name is invalid")
}
for byte in encoded {
guard byte != b'\x00' else {
raise InvalidArgument("link names cannot contain NUL")
}
}
}
///|
fn validate_editable_soft_target(target : String) -> Unit raise Hdf5Error {
let encoded = @utf8.encode(target)
guard encoded.length() > 0 && encoded.length() <= 65535 else {
raise InvalidArgument("soft link target is empty or too long")
}
for byte in encoded {
guard byte != b'\x00' else {
raise InvalidArgument("soft link targets cannot contain NUL")
}
}
}
///|
fn validate_editable_external_target(
target_file : String,
target_path : String,
) -> Unit raise Hdf5Error {
let file = @utf8.encode(target_file)
let path = @utf8.encode(target_path)
guard file.length() > 0 && file.length() <= 65535 else {
raise InvalidArgument("external link target file is empty or too long")
}
guard path.length() > 0 && path.length() <= 65535 else {
raise InvalidArgument("external link target path is empty or too long")
}
for byte in file {
guard byte != b'\x00' else {
raise InvalidArgument("external link target files cannot contain NUL")
}
}
for byte in path {
guard byte != b'\x00' else {
raise InvalidArgument("external link target paths cannot contain NUL")
}
}
}
///|
fn editable_link_index(links : Array[EditableLink], name : String) -> Int32? {
links.search_by(link => link.link.name == name)
}
///|
fn editable_link_creation_order(data : Bytes) -> UInt64? raise Hdf5Error {
let reader = Reader::new(data)
guard reader.read_u8() == b'\x01' else {
raise InvalidField("unsupported link message version")
}
let flags = reader.read_u8().to_int()
if (flags & 0x08) != 0 {
ignore(reader.read_u8())
}
if (flags & 0x04) != 0 {
Some(reader.read_u64_le())
} else {
None
}
}
///|
fn editable_link_storage(
header : ObjectHeader,
offset_size : Int32,
) -> (Bool, UInt64, UInt64, UInt64) raise Hdf5Error {
let undefined = heap_undefined_address(offset_size)
match header.first(msg_link_info) {
Some(message) => {
let reader = Reader::new(message.data)
guard reader.read_u8() == b'\x00' else {
raise UnsupportedFeature("unsupported link info message version")
}
let flags = reader.read_u8().to_int()
guard (flags & 0xFC) == 0 && (flags & 0x03) != 2 else {
raise InvalidField("invalid link info flags")
}
let tracking = (flags & 0x01) != 0
if tracking {
reader.skip(8)
}
let heap_address = reader.read_uint_le(offset_size)
let name_index_address = reader.read_uint_le(offset_size)
let order_index_address = if (flags & 0x02) != 0 {
reader.read_uint_le(offset_size)
} else {
undefined
}
(tracking, heap_address, name_index_address, order_index_address)
}
None => (false, undefined, undefined, undefined)
}
}
///|
fn Hdf5File::editable_dense_link_filters(
self : Hdf5File,
header : ObjectHeader,
) -> MetadataHeapFilters raise Hdf5Error {
if header.first(msg_symbol_table) is Some(_) {
return MetadataHeapFilters::empty()
}
let offset_size = self.superblock.offset_size
let (_, heap_address, _, _) = editable_link_storage(header, offset_size)
if heap_address == heap_undefined_address(offset_size) {
return MetadataHeapFilters::empty()
}
let heap = parse_fractal_heap(
self.bytes,
heap_address,
offset_size,
self.superblock.length_size,
self.superblock.base_address,
custom_filters=self.custom_filters,
)
MetadataHeapFilters::from_heap(heap)
}
///|
fn editable_dense_links(
bytes : Bytes,
heap_address : UInt64,
index_address : UInt64,
offset_size : Int32,
length_size : Int32,
base_address : UInt64,
tracking : Bool,
custom_filters~ : Array[&Hdf5CustomFilter] = [],
) -> Array[EditableLink] raise Hdf5Error {
let heap = parse_fractal_heap(
bytes,
heap_address,
offset_size,
length_size,
base_address,
custom_filters~,
)
let contents = read_v2_btree_records(
bytes,
index_address,
offset_size,
length_size,
base_address,
[5, 6],
"editable link index",
)
let links : Array[EditableLink] = []
for record_index in 0.. order
None =>
if contents.node_type == 6 {
record_order
} else if tracking {
record_order
} else {
record_index.to_uint64()
}
}
links.push({ link, creation_order, })
}
if tracking {
links.sort_by((left, right) => {
if left.creation_order < right.creation_order {
-1
} else if left.creation_order > right.creation_order {
1
} else if left.link.name < right.link.name {
-1
} else if left.link.name > right.link.name {
1
} else {
0
}
})
} else {
links.sort_by((left, right) => {
if left.link.name < right.link.name {
-1
} else if left.link.name > right.link.name {
1
} else {
0
}
})
}
links
}
///|
fn Hdf5File::editable_links(
self : Hdf5File,
header : ObjectHeader,
) -> Array[EditableLink] raise Hdf5Error {
match header.first(msg_symbol_table) {
Some(message) => {
let offset_size = self.superblock.offset_size
let length_size = self.superblock.length_size
let symbol_table = parse_symbol_table_message(
message, offset_size, length_size,
)
let links = read_group_links_v1(
self.bytes,
symbol_table.btree_address,
symbol_table.heap_address,
offset_size,
length_size,
self.superblock.base_address,
)
let editable : Array[EditableLink] = []
for index in 0.. ()
}
let offset_size = self.superblock.offset_size
let length_size = self.superblock.length_size
let (tracking, heap_address, name_index_address, order_index_address) = editable_link_storage(
header, offset_size,
)
if heap_address != heap_undefined_address(offset_size) {
let index_address = if (
tracking ||
!header.messages.any(message => message.msg_type == msg_link)
) &&
order_index_address != heap_undefined_address(offset_size) {
order_index_address
} else if name_index_address != heap_undefined_address(offset_size) {
name_index_address
} else if order_index_address != heap_undefined_address(offset_size) {
order_index_address
} else {
raise InvalidField("dense group has no name or order index")
}
return editable_dense_links(
self.bytes,
heap_address,
index_address,
offset_size,
length_size,
self.superblock.base_address,
tracking,
custom_filters=self.custom_filters,
)
}
guard name_index_address == heap_undefined_address(offset_size) &&
order_index_address == heap_undefined_address(offset_size) else {
raise InvalidField("group index is present without a fractal heap")
}
let links : Array[EditableLink] = []
let messages = header.find(msg_link)
for index in 0.. order
None =>
if tracking {
raise InvalidField("tracked compact link has no creation order")
} else {
index.to_uint64()
}
}
links.push({ link, creation_order, })
}
links
}
///|
fn encode_editable_link(
link : EditableLink,
name : String,
track_order : Bool,
offset_size : Int32,
) -> Bytes raise Hdf5Error {
let item = link.link
if item.cache_type == 0U {
encode_hard_link(
name,
item.object_header_address,
link.creation_order,
track_order,
address_size=offset_size,
)
} else if item.cache_type == 1U || item.cache_type == 2U {
match item.link_target {
Some(target) =>
encode_soft_link(name, target, link.creation_order, track_order)
None => raise InvalidField("soft link has no target")
}
} else if item.cache_type == 64U {
match (item.link_target, item.external_path) {
(Some(target), Some(path)) =>
encode_external_link(
name,
target,
path,
link.creation_order,
track_order,
)
_ => raise InvalidField("external link has incomplete target information")
}
} else {
raise InvalidField(
"unsupported link type for editing: " + item.cache_type.to_string(),
)
}
}
///|
fn encode_editable_compact_link_info(
offset_size : Int32,
track_order : Bool,
max_creation_order : UInt64,
) -> Bytes {
let undefined = heap_undefined_address(offset_size)
let buffer = @buffer.Buffer::Buffer(size_hint=2 + 8 + 2 * offset_size)
buffer.write_byte(b'\x00')
buffer.write_byte(if track_order { b'\x01' } else { b'\x00' })
if track_order {
buffer.write_uint64_le(max_creation_order)
}
write_uint_width(buffer, undefined, offset_size)
write_uint_width(buffer, undefined, offset_size)
buffer.to_bytes()
}
///|
fn encode_editable_dense_links(
entries : Array[WritableDenseHeapEntry],
heap_address : UInt64,
offset_size : Int32,
length_size : Int32,
metadata_filters~ : Array[Filter] = [],
encoded_filters~ : Bytes = b"",
) -> (Bytes, Bytes, Bytes) raise Hdf5Error {
guard writer_dense_entries_fit(entries, kind=WritableDenseLinks) else {
raise InvalidField("dense link metadata is not available")
}
writer_sort_dense_entries(entries)
let (heap_bytes, ids) = encode_writer_dense_heap_storage(
entries,
heap_address,
7,
512,
32,
offset_size~,
length_size~,
metadata_filters~,
encoded_filters~,
)
let index_address = heap_address + heap_bytes.length().to_uint64()
let records : Array[Bytes] = []
for index in 0.. {
let left_order = entries[left].creation_order
let right_order = entries[right].creation_order
if left_order < right_order {
-1
} else if left_order > right_order {
1
} else if entries[left].name < entries[right].name {
-1
} else if entries[left].name > entries[right].name {
1
} else {
0
}
})
let order_records : Array[Bytes] = []
for index in order_indices {
let record = @buffer.Buffer::Buffer(size_hint=15)
record.write_uint64_le(entries[index].creation_order)
writer_write_bytes(record, ids[index])
order_records.push(record.to_bytes())
}
let index_bytes = encode_writer_metadata_btree(
5,
writer_dense_btree_node_size,
11,
records,
index_address,
offset_size~,
length_size~,
)
let order_index_address = index_address + index_bytes.length().to_uint64()
let order_bytes = encode_writer_metadata_btree(
6,
writer_dense_btree_node_size,
15,
order_records,
order_index_address,
offset_size~,
length_size~,
)
(heap_bytes, index_bytes, order_bytes)
}
///|
fn Hdf5File::write_rebuilt_links(
self : Hdf5File,
address : UInt64,
header : ObjectHeader,
links : Array[EditableLink],
tail : @buffer.Buffer,
) -> Bytes raise Hdf5Error {
guard links.length() <= writer_dense_max_link_records else {
raise InvalidArgument("too many links for one group")
}
let offset_size = self.superblock.offset_size
let length_size = self.superblock.length_size
let (existing_tracking, _, _, _) = editable_link_storage(header, offset_size)
let metadata_filters = self.editable_dense_link_filters(header)
let mut max_creation_order = 0UL
for link in links {
if link.creation_order > max_creation_order {
max_creation_order = link.creation_order
}
}
let dense = links.length() > writer_dense_threshold
let symbol_table = header.first(msg_symbol_table) is Some(_)
let tracking = existing_tracking || dense || symbol_table
let new_messages : Array[RebuiltObjectMessage] = []
if dense {
let entries : Array[WritableDenseHeapEntry] = []
for link in links {
entries.push({
name: link.link.name,
hash: writer_name_hash(link.link.name),
data: encode_editable_link(link, link.link.name, true, offset_size),
creation_order: link.creation_order,
flags: b'\x00',
shared_id: None,
})
}
let heap_offset = next_aligned_tail_start(
self.bytes.length(),
tail.length(),
"append dense link metadata",
)
let heap_address = file_offset_to_stored_address(
heap_offset,
self.superblock.base_address,
)
let (heap_bytes, index_bytes, order_bytes) = encode_editable_dense_links(
entries,
heap_address,
offset_size,
length_size,
metadata_filters=metadata_filters.filters,
encoded_filters=metadata_filters.encoded,
)
let start = append_contiguous_dense_metadata(
tail,
self.bytes.length(),
heap_bytes,
index_bytes,
order_bytes,
)
guard start == heap_offset else {
raise InvalidField("dense link metadata address changed")
}
let index_address = heap_address + heap_bytes.length().to_uint64()
let order_address = index_address + index_bytes.length().to_uint64()
new_messages.push({
msg_type: msg_link_info,
flags: b'\x00',
data: encode_dense_storage_info(
true,
max_creation_order,
heap_address,
index_address,
order_address,
offset_size~,
),
creation_order: 0UL,
})
} else {
new_messages.push({
msg_type: msg_link_info,
flags: b'\x00',
data: encode_editable_compact_link_info(
offset_size, tracking, max_creation_order,
),
creation_order: 0UL,
})
for link in links {
new_messages.push({
msg_type: msg_link,
flags: b'\x00',
data: encode_editable_link(link, link.link.name, tracking, offset_size),
creation_order: link.creation_order,
})
}
}
self.write_rebuilt_object_messages(
address,
header,
if symbol_table {
[
_msg_nil, msg_object_continuation, msg_symbol_table, msg_link_info, msg_link,
]
} else {
[_msg_nil, msg_object_continuation, msg_link_info, msg_link]
},
new_messages,
tracking,
tail,
)
}
///|
fn Hdf5File::editable_group(
self : Hdf5File,
path : String,
) -> (UInt64, ObjectHeader, Array[EditableLink]) raise Hdf5Error {
guard self.source is None else {
raise InvalidArgument("link editing requires a bytes-backed Hdf5File")
}
let node = self.resolve(path)
let header = self.object_header_at(node.address)
guard object_kind(header) == Group else {
raise InvalidArgument("link parent is not a group: " + path)
}
(node.address, header, self.editable_links(header))
}
///|
/// Adds a hard link from a group to an existing object in the same file.
pub fn Hdf5File::add_hard_link(
self : Hdf5File,
parent_path : String,
name : String,
target_path : String,
) -> Bytes raise Hdf5Error {
validate_editable_link_name(name)
let (address, header, links) = self.editable_group(parent_path)
guard editable_link_index(links, name) is None else {
raise InvalidArgument("link name already exists: " + name)
}
let target = self.resolve(target_path)
let mut creation_order = 0UL
for link in links {
if link.creation_order >= creation_order {
creation_order = link.creation_order + 1UL
}
}
links.push({
link: {
name,
object_header_address: target.address,
cache_type: 0U,
link_target: None,
external_path: None,
},
creation_order,
})
self.write_rebuilt_links(address, header, links, @buffer.Buffer::Buffer())
}
///|
/// Adds a soft link whose target is interpreted relative to the parent group.
pub fn Hdf5File::add_soft_link(
self : Hdf5File,
parent_path : String,
name : String,
target : String,
) -> Bytes raise Hdf5Error {
validate_editable_link_name(name)
validate_editable_soft_target(target)
let (address, header, links) = self.editable_group(parent_path)
guard editable_link_index(links, name) is None else {
raise InvalidArgument("link name already exists: " + name)
}
let mut creation_order = 0UL
for link in links {
if link.creation_order >= creation_order {
creation_order = link.creation_order + 1UL
}
}
links.push({
link: {
name,
object_header_address: 0UL,
cache_type: 1U,
link_target: Some(target),
external_path: None,
},
creation_order,
})
self.write_rebuilt_links(address, header, links, @buffer.Buffer::Buffer())
}
///|
/// Adds an external link to another HDF5 file.
pub fn Hdf5File::add_external_link(
self : Hdf5File,
parent_path : String,
name : String,
target_file : String,
target_path : String,
) -> Bytes raise Hdf5Error {
validate_editable_link_name(name)
validate_editable_external_target(target_file, target_path)
let (address, header, links) = self.editable_group(parent_path)
guard editable_link_index(links, name) is None else {
raise InvalidArgument("link name already exists: " + name)
}
let mut creation_order = 0UL
for link in links {
if link.creation_order >= creation_order {
creation_order = link.creation_order + 1UL
}
}
links.push({
link: {
name,
object_header_address: 0UL,
cache_type: 64U,
link_target: Some(target_file),
external_path: Some(target_path),
},
creation_order,
})
self.write_rebuilt_links(address, header, links, @buffer.Buffer::Buffer())
}
///|
/// Renames an existing hard, soft or external link while preserving its target
/// and creation order.
pub fn Hdf5File::rename_link(
self : Hdf5File,
parent_path : String,
old_name : String,
new_name : String,
) -> Bytes raise Hdf5Error {
validate_editable_link_name(new_name)
let (address, header, links) = self.editable_group(parent_path)
if old_name == new_name {
return self.bytes
}
let index = match editable_link_index(links, old_name) {
Some(index) => index
None => raise InvalidArgument("link does not exist: " + old_name)
}
guard editable_link_index(links, new_name) is None else {
raise InvalidArgument("link name already exists: " + new_name)
}
links[index] = {
link: { ..links[index].link, name: new_name, },
creation_order: links[index].creation_order,
}
self.write_rebuilt_links(address, header, links, @buffer.Buffer::Buffer())
}
///|
/// Deletes a link and rebuilds the group's compact or dense link storage.
pub fn Hdf5File::delete_link(
self : Hdf5File,
parent_path : String,
name : String,
) -> Bytes raise Hdf5Error {
let (address, header, links) = self.editable_group(parent_path)
let index = match editable_link_index(links, name) {
Some(index) => index
None => raise InvalidArgument("link does not exist: " + name)
}
let rebuilt : Array[EditableLink] = []
for position in 0.. Bytes raise Hdf5Error {
guard self.source is None else {
raise InvalidArgument("object deletion requires a bytes-backed Hdf5File")
}
let target = self.resolve(path)
guard target.address != self.root_address() else {
raise InvalidArgument("the root group cannot be deleted")
}
let group_addresses = [self.root_address()]
for node in self.walk() {
if node.kind == Group && !group_addresses.contains(node.address) {
group_addresses.push(node.address)
}
}
let mut bytes = self.bytes
let mut removed = false
for address in group_addresses {
let file = Hdf5File::parse(bytes)
let header = file.object_header_at(address)
guard object_kind(header) == Group else { continue }
let links = file.editable_links(header)
let rebuilt : Array[EditableLink] = []
for link in links {
if link.link.cache_type == 0U &&
link.link.object_header_address == target.address {
removed = true
} else {
rebuilt.push(link)
}
}
if rebuilt.length() != links.length() {
bytes = file.write_rebuilt_links(
address,
header,
rebuilt,
@buffer.Buffer::Buffer(),
)
}
}
guard removed else {
raise InvalidArgument("object has no removable hard link: " + path)
}
bytes
}