diff --git a/draft.md b/draft.md new file mode 100644 index 0000000..d952bca --- /dev/null +++ b/draft.md @@ -0,0 +1,101 @@ +# Draft IPLD Unixfs Spec + +## Basic Structure + +A Unixfs is either a file or a directory. +The top level IPLD object is a CBOR map with at least two fields: `type` and `data` +and maybe a few other such as a version string or a set of flags. +The `type` field is either `file` or `dir`. + +## IPLD `file` + +If an IPLD file is a leaf its CID type is `raw` (0x55) and has no structure. +Otherwise its CID type is `dag-cbor` (0x71). +The `type` field is set to `file` and the `data` field is an CBOR array. +Each element of the array is CBOR map with the following fields: + + - `data`: link + - `size`: cumulative size of `data` + - `fsize`: (file size) cumulative size of the payload of `data` + +The `fsize` field is omitted if the link is `raw` as it is the same value as size. + +## IPLD `dir` + +An IPLD `dir` represents a directory. +Its CID type is `dag-cbor` (0x71). +The `type` field set to `dir` and the data field is an CBOR map. +The key of the map is a filename and is a CBOR text string encoded in UTF-8. +The value of the map is another CBOR map with the following standard fields: + + - `type` + - `exe`: CBOR boolean: executable bit + - `data`: normally a CBOR link, but can be other types depending on the value of the `type` field + - `size`: cumulative size of `data` + - `fsize`: (file size) cumulative size of the payload of `data` + - `fname`: CBOR byte string: original filename if it differs from the key + +And at least the following optional fields: + + - `ro`: CBOR boolean: read only + - `mtime`: Modification time + - `attr`: CBOR Map: Extended attributes + +Additional fields may be defined. All implementation specific or user +defined fields should be stored under the `attr` field. + +### Directory Types + +The type field is limited to a set of well defined values: + + * _omitted_: regular file + * `dir`: directory entry + * `special`: special file type (fifo, device, etc). + The `data` field is a CBOR Map with at least one field to describe the type. + * `symlink`: symbolic link. The `data` field is the contents of the link. + * `other`: link to other IPLD object, links followed for GC and related operations + * `unknown`: link to unknown objects, links not followed + +### Extended Attributes + +The extended attributes set is not well defined and can be used for vendor extensions and POSIX attributes that don't make sense on non-unix systems. +Stripping this field MUST not change the meaning of the directory entry. +These attributes SHOULD be passed along but do not have to be understood. + +Possible entries: + + * `user`: unix user name + * `uid`: unix numeric uid + * `group`: unix group name + * `gid`: unix numeric gid + * `perm`: full unix permissions + * extended posix attributes + * windows specific attributes + +### Notes + +* Note all standard fields need to be defined for all files types. + + * The `type` field is omitted for regular files. + * The `exe` field is only present when true and only makes sense for regular files + * The `size` and `fsize` are only required when the type is a regular file and possibly a `dir`. + For other types they may be defined if they have a meaningful value. + * The `fsize` field is omitted for files that are leaves (i.e. `raw`) as it is the same value as `size`. + +* IPLD filenames must valid UTF-8 strings which the following additional constraints: + (1) cannot contain the null (0x00) or `/` characters + (2) cannot be the strings: `.` or `..` + Other restricts may be put in place. + If the original filename does not meet these requirements then an implementation MAY transform the file from + the original, so it is valid IPLD file, and store the original file in the `fname` field. + When extracting a directory to the filesystem an implementation + MAY make use of `fname` to restore the original name. + Implementations SHOULD reject invalid files with invalid names by default + and only translate files when a special flag is given. + When extracting implications SHOULD use the IPLD name and not `fname` unless a special flag is given. + +* To save space fields of a directory may be assigned integer values. + Integers have the added benefit of conveying additional meaning based on there values; + for example, to distinguish between standard and optional fields. + +* The `type` field may also be assigned integer values.