You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: UNIXFS.md
+18-19Lines changed: 18 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,17 +61,16 @@ message Data {
61
61
optional uint64 hashType = 5;
62
62
optional uint64 fanout = 6;
63
63
optional uint32 mode = 7;
64
-
optional TimeSpec mtime = 8;
64
+
optional UnixTime mtime = 8;
65
65
}
66
66
67
67
message Metadata {
68
68
optional string MimeType = 1;
69
69
}
70
70
71
-
message TimeSpec {
72
-
required int64 EpochSeconds = 1;
73
-
74
-
optional fixed32 EpochNanoseconds = 2;
71
+
message UnixTime {
72
+
required int64 Seconds = 1;
73
+
optional fixed32 FractionalNanoseconds = 2;
75
74
}
76
75
```
77
76
@@ -96,9 +95,9 @@ UnixFS currently supports two optional metadata fields:
96
95
- The remaining 20 bits are reserved for future use, and are subject to change. Spec implementations **MUST** handle bits they do not expect as follows:
97
96
- For future-proofing the (de)serialization layer must preserve the entire uint32 value during clone/copy operations, modifying only bit values that have a well defined meaning: `clonedValue = ( modifiedBits & 07777 ) | ( originalValue & 0xFFFFF000 )`
98
97
- Implementations of this spec must proactively mask off bits without a defined meaning in the implemented version of the spec: `interpretedValue = originalValue & 07777`
99
-
*`mtime` -- A two-element structure ( `EpochSeconds`, `EpochNanoseconds` ) representing the modification time in seconds relative to the unix epoch `1970-01-01T00:00:00Z`. In contexts where an mtime is mandatory ( e.g. FUSE interfaces ) implementations must treat an unspecified mtime as `0`.
100
-
-`EpochSeconds` represents the amount of seconds after **or before** the epoch. Implementations must be able to gracefully handle negative mtime, even if such a value is not applicable within their domain ( e.g. a POSIX filesystem )
101
-
-`EpochNanoseconds` represents the fractional part of the mtime as the amount of nanoseconds. The valid range for this value is the integer range `[1, 999999999]`. If a fractional part outside of this range is encountered, implementations should consider the entire metadata block invalid and abort processing it. Note that **a fractional value of `0` is NOT valid** - omit the nanosecond value altogether to represent whole seconds.
98
+
*`mtime` -- A two-element structure ( `Seconds`, `FractionalNanoseconds` ) representing the modification time in seconds relative to the unix epoch `1970-01-01T00:00:00Z`. In contexts where an mtime is mandatory ( e.g. FUSE interfaces ) implementations must treat an unspecified mtime as `0`.
99
+
-`Seconds` represents the amount of seconds after **or before** the epoch. Implementations must be able to gracefully handle negative mtime, even if such a value is not applicable within their domain ( e.g. a POSIX filesystem )
100
+
-`FractionalNanoseconds` represents the fractional part of the mtime as the amount of nanoseconds. The valid range for this value is the integer range `[1, 999999999]`. If a fractional part outside of this range is encountered, implementations should consider the entire metadata block invalid and abort processing it. Note that **a fractional value of `0` is NOT valid** - omit the nanosecond value altogether to represent whole seconds.
102
101
103
102
### Deduplication and inlining
104
103
@@ -200,20 +199,20 @@ This scheme would see metadata stored in an external database.
200
199
201
200
The downsides to this are that metadata would not be transferred from one node to another when syncing as [Bitswap] is not aware of the database, and in-tree metadata
202
201
203
-
### TimeSpec protobuf datatype rationale
204
-
205
-
#### EpochSeconds
202
+
### UnixTime protobuf datatype rationale
206
203
207
-
The integer portion of the epoch is represented on the wire using a varint encoding. While this is inefficient for
208
-
negative values, it avoids introducing zig-zag encoding. Negative epoch values will be exceedingly rare, and there
209
-
could very well be value in having such cases stand out, while at the same keeping the "usual" positive values easy
210
-
to eyeball. The varint representing the time of writing this text is 5 bytes long. It will remain so until
211
-
October 26, 3058 ( 34,359,738,367 )
204
+
#### Seconds
212
205
213
-
#### EpichNanoseconds
214
-
Since fractional values will very often be > 2^28 nanoseconds, that part is represented as a 4-byte `fixed32`,
215
-
[as per google's recommendation](https://developers.google.com/protocol-buffers/docs/proto#scalar).
206
+
The integer portion of UnixTime is represented on the wire using a varint encoding. While this is
207
+
inefficient for negative values, it avoids introducing zig-zag encoding. Values before the year 1970
208
+
will be exceedingly rare, and it would be handy having such cases stand out, while at the same keeping
209
+
the "usual" positive values easy to eyeball. The varint representing the time of writing this text is
210
+
5 bytes long. It will remain so until October 26, 3058 ( 34,359,738,367 )
216
211
212
+
#### FractionalNanoseconds
213
+
Fractional values are effectively a random number in the range 0 ~ 999,999,999. Such values will exceed
214
+
2^28 nanoseconds ( 268,435,456 ) in most cases. Therefore, the fractional part is represented as a 4-byte
215
+
`fixed32`, [as per google's recommendation](https://developers.google.com/protocol-buffers/docs/proto#scalar).
0 commit comments