F3.
Copy Markdown
Error returned by the public F3 API.
message is safe to show to a caller. It does not include file bytes,
secrets, or an underlying payload. context carries small identifiers
such as a path, offset, or operation name.
Summary
Functions
A chunk checksum was present and did not match the bytes.
The handle has been closed.
An encoding unit could not be decoded. The message does not include file bytes.
A size, offset, or FlatBuffers field does not describe this file.
The caller passed a value the function does not accept.
The last two bytes are not the F3 magic.
A projected name is not a top-level field.
A value does not fit the field type.
A source operation failed. reason is an Erlang file error atom.
context is merged with %{operation: operation}. The default context
is an empty map.
Row decoding needs the native library and this build does not have it.
A local path does not exist. reason is :enoent.
Builds an error for an operation this experimental version does not perform.
A size field is above the caller's allocation cap. A timed-out request uses this category as well.
The file ends before a required field. context defaults to an empty map.
The file names an encoding this build will not decode.
The postscript version is outside the pinned pair.
Types
@type category() ::
:not_implemented
| :not_found
| :io
| :closed
| :invalid_argument
| :invalid_magic
| :unsupported_version
| :truncated
| :corrupt_metadata
| :unsupported_encoding
| :invalid_projection
| :checksum
| :resource_limit
| :invalid_type
| :native_unavailable
| :corrupt
Stable class of a failure.
:not_implemented is a feature this build does not perform.
:not_found is a missing path or HTTP object. :io is a source failure.
:closed is a handle that was already released. :invalid_argument is a
caller value this function does not accept. :invalid_magic is a file that
does not end in F3. :unsupported_version is a wire pair other than 0.1.
:truncated is a short file or a short HTTP body. :corrupt_metadata is a
footer that does not describe the file. :unsupported_encoding is an
encoding this build will not decode. :invalid_projection is an unknown
column name. :checksum is a stored chunk checksum that did not match.
:resource_limit is a size above the caller's cap, including a timeout.
:invalid_type is a value that does not fit the field. :native_unavailable
means the NIF was not compiled. :corrupt is an encoding unit that could
not be decoded.
@type t() :: %F3.Error{ category: category(), cause: term(), context: map(), message: String.t(), reason: atom() }
One failure.
reason is the operation or the underlying atom, such as :enoent.
category is the stable class. message is safe to show. cause is
reserved and is nil for errors this library builds. context holds
small identifiers. Constructors set context.operation. File bytes and
secrets are not fields.
Functions
A chunk checksum was present and did not match the bytes.
Examples
iex> F3.Error.checksum(:read, "chunk checksum mismatch").category
:checksumThe handle has been closed.
Examples
iex> error = F3.Error.closed(:read)
iex> {error.category, error.context.operation}
{:closed, :read}An encoding unit could not be decoded. The message does not include file bytes.
Examples
iex> F3.Error.corrupt(:decode, "native column term is the wrong shape").category
:corruptA size, offset, or FlatBuffers field does not describe this file.
Examples
iex> F3.Error.corrupt_metadata(:open, "footer is truncated").category
:corrupt_metadataThe caller passed a value the function does not accept.
operation is the public call. message is the sentence returned to the
caller. This does not raise.
Examples
iex> error = F3.Error.invalid_argument(:open, "options must be a keyword list")
iex> error.category
:invalid_argumentThe last two bytes are not the F3 magic.
Examples
iex> F3.Error.invalid_magic(:open).message
"file does not end with the F3 magic"A projected name is not a top-level field.
Examples
iex> error = F3.Error.invalid_projection(:read, "missing")
iex> error.message
"unknown column missing"A value does not fit the field type.
Examples
iex> F3.Error.invalid_type(:writer_write, "id is not an integer").category
:invalid_typeA source operation failed. reason is an Erlang file error atom.
context is merged with %{operation: operation}. The default context
is an empty map.
Examples
iex> error = F3.Error.io(:pread, :eacces)
iex> error.message
"pread failed: eacces"
iex> error = F3.Error.io(:pread, :redirect, %{status: 301})
iex> error.context.status
301A local path does not exist. reason is :enoent.
Examples
iex> error = F3.Error.not_found("missing-file.f3")
iex> error.message
"file not found: missing-file.f3"Builds an error for an operation this experimental version does not perform.
Examples
iex> error = F3.Error.not_implemented(:read)
iex> {error.category, error.message}
{:not_implemented, "read is not implemented in this experimental build"}A size field is above the caller's allocation cap. A timed-out request uses this category as well.
Examples
iex> error = F3.Error.resource_limit(:open, "request timed out", %{timeout_ms: 10})
iex> error.context.timeout_ms
10The file ends before a required field. context defaults to an empty map.
Examples
iex> error = F3.Error.truncated(:open, "file is shorter than the 32 byte postscript")
iex> error.category
:truncatedThe file names an encoding this build will not decode.
Examples
iex> F3.Error.unsupported_encoding(:read, "CUSTOM_WASM is not executed").category
:unsupported_encoding@spec unsupported_version(atom(), non_neg_integer(), non_neg_integer()) :: t()
The postscript version is outside the pinned pair.
Examples
iex> error = F3.Error.unsupported_version(:open, 1, 0)
iex> error.message
"unsupported F3 version 1.0"