Module control 

The control module contains support for parsing Debian RFC 2822-style files into our conventional formats.

What	File Type	Struct
Package Upload	.changes.	package::Changes
Source Package	.dsc	package::Dsc
Build Info	.buildinfo	package::Buildinfo
Binary Package Control	DEBIAN/control	package::BinaryControl
Binary Archive Release	dists/*/InRelease	archive::Release
Binary Archive Index	dists/*/*/binary-*/Packages*	archive::Package
apt sources.list	/etc/apt/sources.list/*.sources	apt::SourcesList
dak command	*.dak-commands	dak::Command

Feature serde

⚠️ Support for directly using ser and de to encode and decode arbitrary Debian-flavored RFC2822 files is possible but not recommended yet. The Serializer and Deserializer implementation is very strict on what it will encode or decode, and the only first-class targets at the moment are the files this crate itself parses. Over time, as this crate matures, this warning will be removed.

Restrictions / Rules on serde support

Use of #[serde(flatten)]

The Debian RFC 2822-like format is not “self describing”. There’s no way to know the type of a value except to have knowledge of the type for a given key.

There’s a long-standing issue due to implementation choices made during the creation of flatten that, when flattening structs, the serde internals will dispatch to the _any helper for the values, rather than the typed helpers, unlike for a normal deserialization.

I can’t see any real useful workarounds and I don’t think serde is going to fix this anytime soon. As a result, I left the _any helper to call back with _str; so flatten will work IFF all fiends are string-based Deserilizations. Weirdly things will break if you use a prim non-String type (like i32 or a bool) in the inner struct while using flatten.

Multiline Behavior

There are three types of Debian RFC2822-style key/value types. Those types are simple (the field must be on all one line), folded (multiple lines, but no semantic meaning), and multiline (repeated continuation lines of a specific format following a possible value on the same line as the key).

This crate treats simple and folded fields as the same. This may break with a strict intepreation of control files, but it is only more lax in what it produces. This may change in the future, do not rely on this behavior.

multiline fields will be treated as a simple or folded field if they’re unpacked into most fields, with the exception of unpacking a multiline into a Vec<_>, which will parse each line into the provided Deserialize traited target. multiline files with a leading value on the same line as the key are not supported as of right now. If you’re parsing such a file, your best bet is to implement serde::Deserialize yourself until this crate matures.

This will export two modules from this package - ser and de. Additionally the crate will add serde::Serialize and serde::Deserialize derives as required.

Feature sequoia

This will add very basic OpenPGP support in a non-exported and private module, as well as one additional function which is exported if serde support is enabled as well under de::from_clearsigned_str.

Feature tokio

This will add support for reading crate::control files from a tokio::io::AsyncRead, via de::from_reader_async

Modules

apt

Rust types to handle Deserialization of a Debian archive files.

archive

Rust types to handle Deserialization of a Debian archive files.

dak

Rust types to handle Deserialization of dak-specific .dak-commands files used by Debian Developers to control the archive.

deserde

Module to use the serde deserialization framework to decode data in Debian’s RFC2822-like format to Rust types.

package

Rust types to handle Deserialization of a Debian archive files.

queued

Rust types to handle Deserialization of queued .commands files used by Debian Developers to control the archive.

serserde

Module to use the serde serialization framework to encode data to Debian’s RFC2822-like format from Rust types.

Structs

DateTime2822

Wrapper type around a String which optionally contains a helper to convert to a ::chrono::DateTime object if the chrono feature flag is enabled.

Delimited

Generic type to hold a bunch of some parseable type delimited with some char DELIM.

Digest

Digest is a specific File’s hash digest.

FileDigest

FileDigest is a specific File’s hash digest and filesize referenced by a control file.

Number

Handle number parsing through a String to patch around a serde bug.

OpenPgpValidatorsequoia

Struct to decode signed Debian control files.

OpenPgpValidatorBuildersequoia

Builder-pattern to create an OpenPgp validator, to decode control files signed by a key in the keyring(s).

RawField

Minimally processed Key-Value pair from the underlying Debian RFC2822-like file.

RawParagraph

RawParagraph contains all the raw, unprocessed and fully stringified RawField values from the underlying document. It is possible to construct an invalid RawParagraph, which may create decoding or encoding issues later on.

Enums

DateTime2822ParseError

Error conditions which may be encountered when working with a DateTime2822.

DigestParseError

Error conditions which may be encountered when working with a Digest field.

Error

Error conditions which may be encountered when working with a RawParagraph file.

FileDigestParseError

Error conditions which may be encountered when working with a FileDigest.

OpenPgpValidatorErrorsequoia

Error conditions which may be encountered when working with OpenPGP signed data within the context of the crate::control module.

Priority

Each package must have a priority value, which is set in the metadata for the Debian archive and is also included in the package’s control files (see Priority). This information is used to control which packages are included in standard or minimal Debian installations.

PriorityParseError

Error conditions which may be encountered when working with a Priority field.

Type Aliases

Architectures

List of Architecture values, seperated with a space.

CommaDelimitedStrings

Wrapper type around a Vec<String> which handles encoding and decoding a list of comma separated String values to and from a single String as seen throughout the control module.

DelimitedStrings

Repeated String values, seperated by DELIM.

DigestMd5

Digest for the MD5 digest algorithm.

DigestSha1

Digest for the SHA1 digest algorithm.

DigestSha256

Digest for the SHA256 digest algorithm.

DigestSha512

Digest for the SHA512 digest algorithm.

FileDigestMd5

A FileDigest set to the HASH_LEN of MD5, 16 bytes.

FileDigestSha1

A FileDigest set to the HASH_LEN of SHA1, 20 bytes.

FileDigestSha256

A FileDigest set to the HASH_LEN of SHA256, 32 bytes.

FileDigestSha512

A FileDigest set to the HASH_LEN of SHA512, 64 bytes.

SpaceDelimitedStrings

Wrapper type around a Vec<String> which handles encoding and decoding a list of space separated String values to and from a single String as seen throughout the control module.