From 416fdb7af91b21b0cfc261a3473c4c3a4d66fdc5 Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Tue, 28 Feb 2023 08:01:58 +0000 Subject: [PATCH 1/3] Add 1.0 log format specification --- formats/log/SPEC_1.0.md | 190 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 formats/log/SPEC_1.0.md diff --git a/formats/log/SPEC_1.0.md b/formats/log/SPEC_1.0.md new file mode 100644 index 0000000..d019f45 --- /dev/null +++ b/formats/log/SPEC_1.0.md @@ -0,0 +1,190 @@ +# Log format + +
+
Namespace
`log`
+
Version
1.0
+
+ +The log format is for storing chronologically sorted data entries. Some common +uses for this data structure include chatrooms, diaries, or microblogs. This +format is designed to be generic so as to accommodate many different use-cases, +and provides a recommended way to extend the format with additional data. + +## Overview + +This format allows a single share to hold many named logs, each of which holds +many chronologically ordered entries. + +Each entry belongs to a single author. The entry may or may not have an +attachment. An entry may or may not be ephemeral and be deleted after a certain +time. + +The chosen name of this format ('log') has nothing to do with append-only logs. +In this log, items may be edited, overwritten, or new entries added which come +before existing entries. + +## Logs + +A share may have many logs, e.g: + +``` ++personalstuff.bxxx + My Journal + Dream Diary + Tasty things I ate lately +``` + +Each of these logs is identified by a numerical ID: + +``` ++personalstuff.bxxx + [0] My Journal + [1] Dream Diary + [2] Tasty things I ate lately +``` + +This log ID is used in the paths of the different documents which belong to a +log: + +- A log entry document +- A log name document +- A log extension document + +All of which have paths prefixed with the following: + +`/log/1.0/{LOG_ID}/` + +Where `{LOG_ID}` is the numerical ID of the log, e.g. `2`. + +As log IDs only ever appear in the paths of log documents, a log's existence is +dependent on the existence of one of these log documents. + +### Determining log IDs + +When creating a document for a new log and determining the log ID for the path: + +- Use `0` in case no documents have been created for any logs in the share. +- Determine the existing log ID with the highest numerical value, and increment + it by 1. + +The second option should be followed even if all the documents referring to the +highest log ID are empty. + +## Log names + +Each log may optionally have a human-readable name associated with it. + +If a log does not have a document describing a human-readable name, clients may +choose to fall back to some other value (e.g. `Log 3`). + +### Log name document path + +The path form of a log name document is: + +``` +/log/1.0/{LOG_ID}/name +``` + +Where `{LOG_ID}` is replaced with the ID of the log that should have this name. + +### Log name document fields + +The `text` field of the document is the desired human-readable name of the log. +It can be any UTF-8 string. + +If the value of the `text` field is an empty string, the document should be +treated the same way as if it were not there at all. + +## Log entries + +A log is made up of many entries, each belonging to a single author. Entries can +be overwritten or wiped, have an optional attachment, or may be ephemeral and +deleted after a certain time. + +### Log entry path + +The path format for an entry without an attachment is: + +``` +/log/1.0//{LOG_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} +``` + +Where `{LOG_ID}` is the numerical ID of the log this entry belongs to, +`{TIMESTAMP}` is the number of milliseconds elapsed since the UNIX epoch, and +`{AUTHOR_ADDRESS}` is the public address of the keypair which was used to sign +this document. + +The path format for a non-ephemeral entry **with** an attachment is: + +``` +/log/1.0/{LOG_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} +``` + +This is the same as before, but is suffixed with `.{ATTACHMENT_EXTENSION}`, +where `{ATTACHMENT_EXTENSION}` is the appropriate file extension for the media +type of the attached data. + +An ephemeral log entry document must place a `!` before the timestamp portion of +the path: + +``` +/log/1.0/{LOG_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} +/log/1.0/{LOG_ID}/!{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} +``` + +The `TIMESTAMP` portion of the path serves two purposes: to help order the +documents chronologically, and to act as a 'created at' timestamp that persists +over subsequent edits. + +The `AUTHOR_ADDRESS` portion is prefixed with a tilde, indicating to Earthstar +that the document at this path can only be written to by the author possessing +the keypair with that address. + +### Log entry fields + +- The `text` property of the document is the content of the entry. It can be any + UTF-8 string. + - If the value of the `text` field is an empty string, the document should be + treated the same way as if it were not there at all. +- A log entry may optionally have an attachment, which can be a file of any + type. +- If the entry is ephemeral, the `deleteAfter` field must be desired expiry time + in UNIX microseconds. + +## Extension documents + +It is often desirable to associate extra attributes with a log and its entries. + +For example, a log could be used to save memorable quotes of a child, where each +entry was a different quote. In our example we wish to extend the log format so +that a client application could display the current age of the child when each +quote was said. To do this, the client would need to know the child's birthday. + +To create our extension, we would create a document at the following path: + +``` +log/1.0/37/ext/kid-quote/birthday +``` + +And the document would have the value of the `text` field set to something like +`2020-01-01`. Our client now has the birthday it needs to determine the age of +the child when the entry was created. + +### Log extension path + +The path format for a log extension document is: + +``` +log/1.0/{LOG_ID}/ext/{EXTENSION_NAMESPACE}/** +``` + +Where `LOG_ID` is the ID of the log being extended, and `EXTENSION_NAMESPACE` is +a string representing the extension form (e.g. `kid-quote`). The glob portion +conveys that after this, the path format is left to the discretion of the +extension in question, and may be as simple or complex as desired, with a single +subsequent path segment or many. + +### Log extension fields + +The fields of a log extension document are not proscribed and their requirements +are left to the designer of the log extension. From 90f1dec67d4bb7b314cd6cd46c8d0c31be32008e Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Thu, 9 Mar 2023 10:58:53 +0000 Subject: [PATCH 2/3] Log -> Sequence --- formats/log/SPEC_1.0.md | 190 ---------------------------------- formats/sequence/SPEC_1.0.md | 192 +++++++++++++++++++++++++++++++++++ 2 files changed, 192 insertions(+), 190 deletions(-) delete mode 100644 formats/log/SPEC_1.0.md create mode 100644 formats/sequence/SPEC_1.0.md diff --git a/formats/log/SPEC_1.0.md b/formats/log/SPEC_1.0.md deleted file mode 100644 index d019f45..0000000 --- a/formats/log/SPEC_1.0.md +++ /dev/null @@ -1,190 +0,0 @@ -# Log format - -
-
Namespace
`log`
-
Version
1.0
-
- -The log format is for storing chronologically sorted data entries. Some common -uses for this data structure include chatrooms, diaries, or microblogs. This -format is designed to be generic so as to accommodate many different use-cases, -and provides a recommended way to extend the format with additional data. - -## Overview - -This format allows a single share to hold many named logs, each of which holds -many chronologically ordered entries. - -Each entry belongs to a single author. The entry may or may not have an -attachment. An entry may or may not be ephemeral and be deleted after a certain -time. - -The chosen name of this format ('log') has nothing to do with append-only logs. -In this log, items may be edited, overwritten, or new entries added which come -before existing entries. - -## Logs - -A share may have many logs, e.g: - -``` -+personalstuff.bxxx - My Journal - Dream Diary - Tasty things I ate lately -``` - -Each of these logs is identified by a numerical ID: - -``` -+personalstuff.bxxx - [0] My Journal - [1] Dream Diary - [2] Tasty things I ate lately -``` - -This log ID is used in the paths of the different documents which belong to a -log: - -- A log entry document -- A log name document -- A log extension document - -All of which have paths prefixed with the following: - -`/log/1.0/{LOG_ID}/` - -Where `{LOG_ID}` is the numerical ID of the log, e.g. `2`. - -As log IDs only ever appear in the paths of log documents, a log's existence is -dependent on the existence of one of these log documents. - -### Determining log IDs - -When creating a document for a new log and determining the log ID for the path: - -- Use `0` in case no documents have been created for any logs in the share. -- Determine the existing log ID with the highest numerical value, and increment - it by 1. - -The second option should be followed even if all the documents referring to the -highest log ID are empty. - -## Log names - -Each log may optionally have a human-readable name associated with it. - -If a log does not have a document describing a human-readable name, clients may -choose to fall back to some other value (e.g. `Log 3`). - -### Log name document path - -The path form of a log name document is: - -``` -/log/1.0/{LOG_ID}/name -``` - -Where `{LOG_ID}` is replaced with the ID of the log that should have this name. - -### Log name document fields - -The `text` field of the document is the desired human-readable name of the log. -It can be any UTF-8 string. - -If the value of the `text` field is an empty string, the document should be -treated the same way as if it were not there at all. - -## Log entries - -A log is made up of many entries, each belonging to a single author. Entries can -be overwritten or wiped, have an optional attachment, or may be ephemeral and -deleted after a certain time. - -### Log entry path - -The path format for an entry without an attachment is: - -``` -/log/1.0//{LOG_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} -``` - -Where `{LOG_ID}` is the numerical ID of the log this entry belongs to, -`{TIMESTAMP}` is the number of milliseconds elapsed since the UNIX epoch, and -`{AUTHOR_ADDRESS}` is the public address of the keypair which was used to sign -this document. - -The path format for a non-ephemeral entry **with** an attachment is: - -``` -/log/1.0/{LOG_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} -``` - -This is the same as before, but is suffixed with `.{ATTACHMENT_EXTENSION}`, -where `{ATTACHMENT_EXTENSION}` is the appropriate file extension for the media -type of the attached data. - -An ephemeral log entry document must place a `!` before the timestamp portion of -the path: - -``` -/log/1.0/{LOG_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} -/log/1.0/{LOG_ID}/!{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} -``` - -The `TIMESTAMP` portion of the path serves two purposes: to help order the -documents chronologically, and to act as a 'created at' timestamp that persists -over subsequent edits. - -The `AUTHOR_ADDRESS` portion is prefixed with a tilde, indicating to Earthstar -that the document at this path can only be written to by the author possessing -the keypair with that address. - -### Log entry fields - -- The `text` property of the document is the content of the entry. It can be any - UTF-8 string. - - If the value of the `text` field is an empty string, the document should be - treated the same way as if it were not there at all. -- A log entry may optionally have an attachment, which can be a file of any - type. -- If the entry is ephemeral, the `deleteAfter` field must be desired expiry time - in UNIX microseconds. - -## Extension documents - -It is often desirable to associate extra attributes with a log and its entries. - -For example, a log could be used to save memorable quotes of a child, where each -entry was a different quote. In our example we wish to extend the log format so -that a client application could display the current age of the child when each -quote was said. To do this, the client would need to know the child's birthday. - -To create our extension, we would create a document at the following path: - -``` -log/1.0/37/ext/kid-quote/birthday -``` - -And the document would have the value of the `text` field set to something like -`2020-01-01`. Our client now has the birthday it needs to determine the age of -the child when the entry was created. - -### Log extension path - -The path format for a log extension document is: - -``` -log/1.0/{LOG_ID}/ext/{EXTENSION_NAMESPACE}/** -``` - -Where `LOG_ID` is the ID of the log being extended, and `EXTENSION_NAMESPACE` is -a string representing the extension form (e.g. `kid-quote`). The glob portion -conveys that after this, the path format is left to the discretion of the -extension in question, and may be as simple or complex as desired, with a single -subsequent path segment or many. - -### Log extension fields - -The fields of a log extension document are not proscribed and their requirements -are left to the designer of the log extension. diff --git a/formats/sequence/SPEC_1.0.md b/formats/sequence/SPEC_1.0.md new file mode 100644 index 0000000..0c445db --- /dev/null +++ b/formats/sequence/SPEC_1.0.md @@ -0,0 +1,192 @@ +# Sequence format + +
+
Namespace
`sequence`
+
Version
1.0
+
+ +The sequence format is for storing chronologically sorted data entries. Some +common uses for this data structure include chatrooms, diaries, or microblogs. +This format is designed to be generic so as to accommodate many different +use-cases, and provides a recommended way to extend the format with additional +data. + +## Overview + +This format allows a single share to hold many named sequences, each of which +holds many chronologically ordered entries. + +Each entry belongs to a single author. The entry may or may not have an +attachment. An entry may or may not be ephemeral and be deleted after a certain +time. + +## Sequences + +A share may have many sequences, e.g: + +``` ++personalstuff.bxxx + My Journal + Dream Diary + Tasty things I ate lately +``` + +Each of these sequences is identified by a numerical ID: + +``` ++personalstuff.bxxx + [0] My Journal + [1] Dream Diary + [2] Tasty things I ate lately +``` + +This sequence ID is used in the paths of the different documents which belong to +a sequence: + +- A sequence entry document +- A sequence name document +- A sequence extension document + +All of which have paths prefixed with the following: + +`/sequence/1.0/{SEQUENCE_ID}/` + +Where `{SEQUENCE_ID}` is the numerical ID of the sequence, e.g. `2`. + +As sequence IDs only ever appear in the paths of sequence documents, a +sequence's existence is dependent on the existence of one of these sequence +documents. + +### Determining sequence IDs + +When creating a document for a new sequence and determining the sequence ID for +the path: + +- Use `0` in case no documents have been created for any sequences in the share. +- Determine the existing sequence ID with the highest numerical value, and + increment it by 1. + +The second option should be followed even if all the documents referring to the +highest sequence ID are empty (indicating deletion). + +## Sequence names + +Each sequence may optionally have a human-readable name associated with it. + +If a sequence does not have a document describing a human-readable name, clients +may choose to fall back to some other value (e.g. `Sequence 3`). + +### Sequence name document path + +The path form of a sequence name document is: + +``` +/sequence/1.0/{SEQUENCE_ID}/name +``` + +Where `{SEQUENCE_ID}` is replaced with the ID of the sequence that should have +this name. + +### Sequence name document fields + +The `text` field of the document is the desired human-readable name of the +sequence. It can be any UTF-8 string. + +If the value of the `text` field is an empty string, the document should be +treated the same way as if it were not there at all. + +## Sequence entries + +A sequence is made up of many entries, each belonging to a single author. +Entries can be overwritten or wiped, have an optional attachment, or may be +ephemeral and deleted after a certain time. + +### Sequence entry path + +The path format for an entry without an attachment is: + +``` +/sequence/1.0/{SEQUENCE_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} +``` + +Where `{SEQUENCE_ID}` is the numerical ID of the sequence this entry belongs to, +`{TIMESTAMP}` is the number of milliseconds elapsed since the UNIX epoch, and +`{AUTHOR_ADDRESS}` is the public address of the keypair which was used to sign +this document. + +The path format for a non-ephemeral entry **with** an attachment is: + +``` +/sequence/1.0/{SEQUENCE_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} +``` + +This is the same as before, but is suffixed with `.{ATTACHMENT_EXTENSION}`, +where `{ATTACHMENT_EXTENSION}` is the appropriate file extension for the media +type of the attached data. + +An ephemeral sequence entry document must place a `!` before the timestamp +portion of the path: + +``` +/sequence/1.0/{SEQUENCE_ID}/{TIMESTAMP}~{AUTHOR_ADDRESS} +/sequence/1.0/{SEQUENCE_ID}/!{TIMESTAMP}~{AUTHOR_ADDRESS}.{ATTACHMENT_EXTENSION} +``` + +The `TIMESTAMP` portion of the path serves two purposes: to help order the +documents chronologically, and to act as a 'created at' timestamp that persists +over subsequent edits. + +The `AUTHOR_ADDRESS` portion is prefixed with a tilde, indicating to Earthstar +that the document at this path can only be written to by the author possessing +the keypair with that address. + +### Sequence entry fields + +- The `text` property of the document is the content of the entry. It can be any + UTF-8 string. + - If the value of the `text` field is an empty string, the document should be + treated the same way as if it were not there at all. +- A sequence entry may optionally have an attachment, which can be a file of any + type. +- If the entry is ephemeral, the `deleteAfter` field must be desired expiry time + in UNIX microseconds. + +## Extension documents + +It is often desirable to associate extra attributes with a sequence and its +entries. + +For example, a sequence could be used to save memorable quotes of a child, where +each entry was a different quote. In our example we wish to extend the sequence +format so that a client application could display the current age of the child +when each quote was said. To do this, the client would need to know the child's +birthday. + +To create our extension, we would create a document at the following path: + +``` +sequence/1.0/37/ext/kid-quote/birthday +``` + +And the document would have the value of the `text` field set to something like +`2020-01-01`. Our client now has the birthday it needs to determine the age of +the child when the entry was created. + +### Sequence extension path + +The path format for a sequence extension document is: + +``` +sequence/1.0/{SEQUENCE_ID}/ext/{EXTENSION_NAMESPACE}/** +``` + +Where `SEQUENCE_ID` is the ID of the sequence being extended, and +`EXTENSION_NAMESPACE` is a string representing the extension form (e.g. +`kid-quote`). The glob portion conveys that after this, the path format is left +to the discretion of the extension in question, and may be as simple or complex +as desired, with a single subsequent path segment or many. + +### Sequence extension fields + +The fields of a sequence extension document are not proscribed and their +requirements are left to the designer of the sequence extension. From 8b117cf4b57cc5460a249442d0b96fccff668603 Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Thu, 9 Mar 2023 10:59:03 +0000 Subject: [PATCH 3/3] Fix typo in about spec --- formats/about/SPEC_1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/formats/about/SPEC_1.0.md b/formats/about/SPEC_1.0.md index f2edb5a..ceaad1b 100644 --- a/formats/about/SPEC_1.0.md +++ b/formats/about/SPEC_1.0.md @@ -39,7 +39,7 @@ at any time, and which can differ between each share. The path format of a display name document is: ``` -`/about/1.0/~{KEYPAIR_ADDRESS}/displayName +/about/1.0/~{KEYPAIR_ADDRESS}/displayName ``` ### Display name document fields