docs: change mode and mtime to messages

[achingbrain]

As currently defined the closest we can come to removing a mode/mtime previously set on a file is to set it's value to 0, which works in that the CID returns to what it would have been pre-metadata, but when combined with default file/dir modes also has the side effect of making it impossible to actually set the file mode to 0.

Worse, if you set the file mode to 0 you actually get the default file mode back of 0644 which is probably not what you intended.

The proposed solution is to store mode and mtime values in dedicated protobuf messages in order to represent the case where they have not been set.

The protobuf spec says:

For message fields, the field is not set. Its exact value is language-dependent.

So we are free to represent them as undefined when they have not been set.

mtime is changed too because if I add some metadata to a file, I should be able to remove it - it shouldn't be a one-way thing.

This PR also removes the default mode values as otherwise it's not an opt-in upgrade.

[achingbrain]

Sample implementation: ipfs/js-ipfs-unixfs#38

[ribasushi]

LGTM as per our Zoom conversation

[aschmahmann]

For message fields, the field is not set. Its exact value is language-dependent.

So we are free to represent them as undefined when they have not been set.

It seems like we are effectively adding a new restriction on how protobuf deserialization should work for UnixFSv1.5.

This isn't necessarily a problem, but if we do this instead of something that it is protobuf spec compliant (e.g. the not so pretty #229 (comment)), we should definitely make sure this is highlighted to help future implementers not make a mistake here.

[Stebalien]

The whole zero-value nonsense is a protobuf version 3 restriction. Version 2, the version we're using here, allows one to detect the presence/absence of a field.

Is there any reason we can't rely on this?

[achingbrain]

@Stebalien interesting, that would certainly be preferable.

I've got protoc to generate JS code from our protobuf definitions and it does indeed have hasXXX method in there which would do the trick. protons doesn't do this, hence the confusion, but I can PR that in.

I haven't been able to get protoc to generate the same sort of methods for go, presumably it's possible? Unless I've missed something the doc you linked to doesn't mention any way of detecting the presence/absence of a field.

[Stebalien]

I haven't been able to get protoc to generate the same sort of methods for go, presumably it's possible? Unless I've missed something the doc you linked to doesn't mention any way of detecting the presence/absence of a field.

In go, protoc will put values behind pointers. So Data.Mtime will be a pointer to a uint64. If the pointer is nil, it's unset.

[ribasushi]

In light of #230 (comment) ( go having an implicit nil indirection, and js having a has... method ), I think this change is no longer needed.