bookclerk_plugin_abi::metadata_files
The checks the host runs on what a metadataFiles plugin returns and on
what it sends one.
A metadata-file dialect turns the bytes of a sidecar (Audiobookshelf
metadata.json, OPF, NFO, CUE, ...) into a MetadataFileRecord and
renders a record back into bytes. The plugin is jailed with no file or
network grants, but its replies are still untrusted: every record is
checked here before the host stores a claim from it. The checks are
sans-IO, so the metadata_file_record fuzz target and the host run the
same code.
Two layers:
validate_metadata_file_recordchecks a record on its own: caps, text shape, date shape, chapter order, and that every value it carries is for a field it says the file states.check_record_against_dialectchecks it against the dialect the manifest declares: a record may not state a field or credit role its dialect does not carry.
| Item | Kind | Summary |
|---|---|---|
MetadataFileDialect |
struct | One dialect as the plugin's manifest declares it: the fields its format carries and whether it can write files. The host builds this from the [[metadata_files.dialects]] row it routed a file to. |
MetadataFileError |
enum | Why a metadata-file request or reply was refused. |
is_dialect_id |
function | Whether id follows the ABI identifier rule a-z{0,63}. |
is_plain_file_name |
function | Whether name is a plain file name: non-empty, at most MAX_METADATA_FILE_NAME_BYTES, not . or .., and free of /, \ and control characters. |
is_partial_date |
function | Whether date is YYYY, YYYY-MM or YYYY-MM-DD with a real month and a day the month can hold (29 February only in a leap year). |
fields_with_values |
function | The fields a record carries a value for, in MetadataField order. |
validate_metadata_file_record |
function | Checks a record on its own, without its dialect. |
check_record_against_dialect |
function | Checks a record against the dialect that produced it: present names only fields the dialect carries and creditRoles only roles it carries. |
check_parse_params |
function | Checks a MetadataFiles.parse request before it is sent: a dialect id, a plain file name, and bytes within MAX_METADATA_FILE_BYTES. |
check_render_params |
function | Checks a MetadataFiles.render request before it is sent: a dialect id, fields named once each, existing bytes within MAX_METADATA_FILE_BYTES, at most MAX_METADATA_AUDIO_FILES audio files with plain names and durations a JavaScript number holds exactly, and a record that passes validate_metadata_file_record. |
check_render_against_dialect |
function | Checks a render request against the dialect it names: the dialect writes, and every field to write is one it carries. |
check_rendered |
function | Checks a rendered file: within MAX_METADATA_FILE_BYTES. An empty file is allowed: it means the dialect has nothing left to write, and the host decides whether to keep the empty file or remove it. |
decode_metadata_file_record_bytes |
function | Decodes one unpacked single-segment Cap'n Proto MetadataFileRecord, the form the fuzz target feeds. |
encode_metadata_file_record_bytes |
function | Encodes record as an unpacked single-segment Cap'n Proto message, the inverse of decode_metadata_file_record_bytes. |
MAX_METADATA_FILE_NAME_BYTES |
constant | Longest file name MetadataFiles.parse accepts, in UTF-8 bytes (the usual file-system component limit). |
MAX_METADATA_DIALECT_ID_BYTES |
constant | Longest dialect id, in bytes; dialect ids follow the ABI identifier rule. |
pub struct MetadataFileDialect {
pub id: String,
pub fields: Vec<MetadataField>,
pub credit_roles: Vec<CreditRole>,
pub writes: bool,
}
One dialect as the plugin's manifest declares it: the fields its format
carries and whether it can write files. The host builds this from the
[[metadata_files.dialects]] row it routed a file to.
Fields
id: Dialect id ([a-z][a-z0-9_]{0,63}), unique within the plugin.fields: Fields the format carries; a record may state only these.credit_roles: Credit roles the format carries whenfieldsholdsMetadataField::Credits; empty otherwise.writes: Whether the dialect renders files (MetadataFiles.render), not only reads them.
Implements: Clone, Debug, Eq, PartialEq
pub enum MetadataFileError {
BadDialectId,
BadFileName,
BadFileSize(usize),
DuplicateField(MetadataField),
DuplicateCreditRole(CreditRole),
ValueNotPresent(MetadataField),
CreditRoleNotStated(CreditRole),
TooMany(&'static str),
BadText(&'static str),
BadDate,
BadChapters,
FieldNotCarried(MetadataField),
CreditRoleNotCarried(CreditRole),
ReadOnlyDialect,
WrongDialect,
BadAudioDuration,
}
Why a metadata-file request or reply was refused.
Variants
BadDialectId: A dialect id is not[a-z][a-z0-9_]{0,63}.BadFileName: A file name is empty, too long, a dot name, or holds a path separator or a control character.BadFileSize: File bytes are overMAX_METADATA_FILE_BYTES(or a rendered file is empty).DuplicateField: A field appears twice in a field list (presentor a render request'sfields).DuplicateCreditRole: A credit role appears twice increditRoles.ValueNotPresent: The record carries a value for a field missing frompresent.CreditRoleNotStated: A credit's role is not increditRoles.TooMany: A list is longer than its cap.BadText: A text value is empty where it may not be, over its cap, or holds a NUL or another control character it may not.BadDate:publishedAtis notYYYY,YYYY-MMorYYYY-MM-DD.BadChapters: Chapters are out of order or nest more than one level at a time.FieldNotCarried: The record or request names a field the dialect does not carry.CreditRoleNotCarried: The record names a credit role the dialect does not carry.ReadOnlyDialect: A render request named a dialect that only reads.WrongDialect: A request named a dialect other than the one being checked against.BadAudioDuration: An audio file's duration is past what a JavaScript number holds exactly (2^53 - 1 ms).
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub fn is_dialect_id(id: &str) -> bool
Whether id follows the ABI identifier rule [a-z][a-z0-9_]{0,63}.
id- The dialect id to check.
True when the id is well formed.
pub fn is_plain_file_name(name: &str) -> bool
Whether name is a plain file name: non-empty, at most
MAX_METADATA_FILE_NAME_BYTES, not . or .., and free of /, \
and control characters.
name- The file name to check.
True when the name names one file with no folder.
pub fn is_partial_date(date: &str) -> bool
Whether date is YYYY, YYYY-MM or YYYY-MM-DD with a real month
and a day the month can hold (29 February only in a leap year).
date- The date text to check.
True when the date has one of the three shapes and is a real date.
pub fn fields_with_values(record: &MetadataFileRecord) -> Vec<MetadataField>
The fields a record carries a value for, in MetadataField order.
A value is anything other than the zero value: a set text, a non-empty
list, a known abridgement or expression kind, or a duration. Credit
roles count as a value for MetadataField::Credits.
record- The record to inspect.
Every field with a value.
pub fn validate_metadata_file_record(
record: &MetadataFileRecord,
) -> Result<(), MetadataFileError>
Checks a record on its own, without its dialect.
The rules:
presentandcreditRolesname each entry at most once, and every field with a value (seefields_with_values) is inpresent;- every credit's role is in
creditRoles; - lists stay within
MAX_METADATA_FILE_LIST_ENTRIESand chapters withinMAX_METADATA_FILE_CHAPTERS; - text values are within
MAX_METADATA_FILE_TEXT_BYTES(the description withinMAX_METADATA_FILE_DESCRIPTION_BYTES), labels and names are non-blank single lines, and only the description may hold line breaks or tabs; publishedAtpassesis_partial_date;- chapter starts never decrease, the first chapter has depth 0, and each chapter is at most one level deeper than the one before it.
record- A record a dialect returned (untrusted).
Ok(()) when the record keeps every rule.
The first rule the record breaks, as a MetadataFileError.
pub fn check_record_against_dialect(
record: &MetadataFileRecord,
dialect: &MetadataFileDialect,
) -> Result<(), MetadataFileError>
Checks a record against the dialect that produced it: present names
only fields the dialect carries and creditRoles only roles it carries.
record- A record that already passedvalidate_metadata_file_record.dialect- The dialect the host routed the file to.
Ok(()) when the record stays inside the dialect.
MetadataFileError::FieldNotCarried or
MetadataFileError::CreditRoleNotCarried.
pub fn check_parse_params(
params: &MetadataFileParseParams,
) -> Result<(), MetadataFileError>
Checks a MetadataFiles.parse request before it is sent: a dialect id,
a plain file name, and bytes within MAX_METADATA_FILE_BYTES.
params- The request the host is about to send.
Ok(()) when the request is well formed.
MetadataFileError::BadDialectId, MetadataFileError::BadFileName
or MetadataFileError::BadFileSize.
pub fn check_render_params(
params: &MetadataFileRenderParams,
) -> Result<(), MetadataFileError>
Checks a MetadataFiles.render request before it is sent: a dialect id,
fields named once each, existing bytes within MAX_METADATA_FILE_BYTES,
at most MAX_METADATA_AUDIO_FILES audio files with plain names and
durations a JavaScript number holds exactly, and a record that passes
validate_metadata_file_record.
params- The request the host is about to send.
Ok(()) when the request is well formed.
The first rule the request breaks.
pub fn check_render_against_dialect(
params: &MetadataFileRenderParams,
dialect: &MetadataFileDialect,
) -> Result<(), MetadataFileError>
Checks a render request against the dialect it names: the dialect writes, and every field to write is one it carries.
params- A request that already passedcheck_render_params.dialect- The dialect from the manifest.
Ok(()) when the dialect can write every requested field.
MetadataFileError::WrongDialect, MetadataFileError::ReadOnlyDialect
or MetadataFileError::FieldNotCarried.
pub fn check_rendered(rendered: &MetadataFileRendered) -> Result<(), MetadataFileError>
Checks a rendered file: within MAX_METADATA_FILE_BYTES. An empty file
is allowed: it means the dialect has nothing left to write, and the host
decides whether to keep the empty file or remove it.
rendered- A dialect'srenderreply (untrusted).
Ok(()) when the host may write the bytes.
MetadataFileError::BadFileSize.
pub fn decode_metadata_file_record_bytes(bytes: &[u8]) -> Result<MetadataFileRecord>
Decodes one unpacked single-segment Cap'n Proto MetadataFileRecord, the
form the fuzz target feeds.
bytes- The message bytes (untrusted).
The decoded record.
Returns the Cap'n Proto error the framing or the codec reports.
pub fn encode_metadata_file_record_bytes(record: &MetadataFileRecord) -> Result<Vec<u8>>
Encodes record as an unpacked single-segment Cap'n Proto message, the
inverse of decode_metadata_file_record_bytes.
record- The record to encode.
The message bytes.
Returns the Cap'n Proto error the builder reports.
pub const MAX_METADATA_FILE_NAME_BYTES: usize = 255;
Longest file name MetadataFiles.parse accepts, in UTF-8 bytes (the
usual file-system component limit).
pub const MAX_METADATA_DIALECT_ID_BYTES: usize = 64;
Longest dialect id, in bytes; dialect ids follow the ABI identifier rule.
Generated from crates/bookclerk-plugin-abi at main · View as Markdown