X-Git-Url: https://git.ladys.computer/x_status_git/blobdiff_plain/2659b92ca7ae70783227a5de0c000e34b984e2c2..3b743898578b26b6a835c3e012eccccd6ea665f2:/README.markdown diff --git a/README.markdown b/README.markdown index 2c71b22..0d7d027 100644 --- a/README.markdown +++ b/README.markdown @@ -1,6 +1,6 @@ -# Status.git +# x_status_git -A minimal git‐based self‐hosted status publishing solution. +A minimal git‐based microblog. ## What It Is @@ -71,7 +71,9 @@ You’ll need to supply some variables there, too :— ## Server Configuration Your server should be configured to serve the following files from the - provided `PUBLIC_DIRECTORY` in response to the following requests :— + provided `PUBLIC_DIRECTORY` in response to the following requests. +For people using Caddy to serve their content, a sample `Caddyfile` is + included in this repository. ### H·T·M·L responses @@ -81,6 +83,15 @@ Note that these paths **do not** have a trailing slash. + **`GET /`**: Serve the file at `/index.html`. + A `Link` header with the value + `;rel=meta;type="application/ld+json"` (or + equivalent) **must** be provided. + + + **`GET /about`**: + Serve the file at `/.about.html`. + A `Link` header with the value + `;rel=meta;type="application/ld+json"` (or + equivalent) **must** be provided. + **`GET /statuses`**: Serve the file at `/.statuses.html`. @@ -88,13 +99,13 @@ Note that these paths **do not** have a trailing slash. `;rel=meta;type="application/ld+json"` (or equivalent) **must** be provided. - + **`GET /$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`): + + **`GET /statuses/$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`): Serve the file at `/.topic.html`. A `Link` header with the value `;rel=meta;type="application/ld+json"` (or equivalent) **must** be provided. - + **`GET /$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`): + + **`GET /statuses/$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`): Serve the file at `/.status.html`. A `Link` header with the value `;rel=meta;type="application/ld+json"` (or @@ -119,6 +130,16 @@ Note that these paths **do not** have a trailing slash. `;rel=meta;type="application/ld+json"` (or equivalent) **must** be provided. +### X·H·T·M·L responses + +These responses **must** be served with a `Content-Type` of + `application/xhtml+xml` (or equivalent). +Note that these paths **do not** have a trailing slash. + + + **`GET /$IRI`** (where `$IRI` contains a colon and no slash): + Serve the file at `/.lookup.xhtml`. + This can be used to look up statuses by their identifier. + ### Json‐L·D responses These responses **should** be served with a `Content-Type` of @@ -126,10 +147,13 @@ These responses **should** be served with a `Content-Type` of In all cases, for `/$PATH.jsonld`, this just serves the file at `/$PATH/index.jsonld`. + + **`GET /about.jsonld`**: + Serve the file at `/about/index.jsonld`. + + **`GET /statuses.jsonld`**: Serve the file at `/statuses/index.jsonld`. - + **`GET /$YYYY-MM.jsonld`** (where `$YYYY-MM` is an + + **`GET /statuses/$YYYY-MM.jsonld`** (where `$YYYY-MM` is an `xsd:gYearMonth`): Serve the file at `/$YYYY-MM/index.jsonld`. @@ -140,6 +164,24 @@ In all cases, for `/$PATH.jsonld`, this just serves the file at `[0-9A-Za-z_-]+`): Serve the file at `/topics/$TOPIC/index.jsonld`. +### Atom responses + +These responses **should** be served with a `Content-Type` of + `application/atom+xml`. +In all cases, for `/$PATH.atom`, this just serves the file at + `/$PATH/index.atom`. + + + **`GET /statuses.atom`**: + Serve the file at `/statuses/index.atom`. + + + **`GET /statuses/$YYYY-MM.atom`** (where `$YYYY-MM` is an + `xsd:gYearMonth`): + Serve the file at `/$YYYY-MM/index.atom`. + + + **`GET /topics/$TOPIC.atom`** (where `$TOPIC` matches + `[0-9A-Za-z_-]+`): + Serve the file at `/topics/$TOPIC/index.atom`. + ### Other Headers All responses **should** have a `Access-Control-Allow-Origin` header @@ -195,6 +237,13 @@ The files which represent a status are as follows :— The contents of this file **must** give the author’s URL, optionally followed by a trailing newline. + + **`2=TITLE`** (where `TITLE` might be anything): + This file is **optional** and indicates the title of the status. + The value of `TITLE` **should** be a file·system‐friendly version + of the title, but is ignored. + The contents of this file **must** give the title of the status, + optionally followed by a trailing newline. + + **`3=YYYY-MM-DD`** (where `YYYY-MM-DD` is a date): This file is **required** and indicates the date of the status. Only one date is currently supported. @@ -219,7 +268,7 @@ The files which represent a status are as follows :— Files with names that begin with the strings `2=` or `x_status_git_` are reserved for backwards‐compatible extensions. -Status.git has no opinion on how these files make their way into the +x_status_git has no opinion on how these files make their way into the Git repository, except that all the files for a single status should be added in the same commit. The intention is that the simple nature of these files will make them @@ -227,41 +276,92 @@ The intention is that the simple nature of these files will make them ## I Am Computer, How Do I Get Status? -Assume you are given a U·R·L to a status collection, like `/statuses`, - `/YYYY-MM`, or `/topics/my_topic`. -Make a `HEAD` request to this U·R·L. -If there is a `Link` header with a `rel` of `meta` and a `type` of - `application/ld+json`, make a `GET` request to that U·R·L instead. -Otherwise, make a `GET` request to the U·R·L you were given. +Assume you are given a U·R·L `resource_url` which you think points to + some kind of x_status_git resource. +Start by resolving it as follows :— + +01. Make a `HEAD` request to `resource_url`. + +02. If there is a `Link` header with a `rel` of `meta` and a `type` of + `application/ld+json`, set `resource_url` to the URL provided in + that header and restart these steps from step 1. + +03. Make a `GET` request to `resource_url` and let `response` be the + response. + +04. Set `document` as follows :— + + 01. If the `Content-Type` header of `response` has a type of `text` + and subtype of `html`, let `document` be the result of + processing the body of `response` into a D·O·M tree as an + H·T·M·L document . + It is an error if this process fails. + + 02. If the `Content-Type` header of `response` has a type of + `application` and a subtype which is `xml` or which ends in + `+xml`, let `document` be the result of processing the body + of `response` into a D·O·M tree as an X·M·L document . + It is an error if this process fails. + + 03. Otherwise, let `document` be null. -Assuming the U·R·L you were given was valid, you will receive a - Json‐L·D response with a `@type` which is either an - `OrderedCollection` or an `OrderedCollectionPage`. -One of the following will be true :— +05. If `document` is not null :— - + The response is an `OrderedCollectionPage`. - Its `items` will be an array of statuses, and the `prev` and - `next` properties will give U·R·Ls for previous and next - pages of statuses (if any exist). + 01. If there is a `` element in either the H·T·M·L namespace + or the Atom namespace in `document` with a `rel` of `meta` + and a `type` of `application/ld+json`, set `resource_url` to + the `href` of that `` element and restart these steps + from step 1. + If multiple such elements exist, choose the first one. - + The response is an `OrderedCollection` with `first` and - `current` properties. - These properies give the U·R·Ls for the first and latest pages - of statuses, which you can fetch and process as above. + 02. Otherwise, it is an error. - + Otherwise, the `items` property will be an array of every - status in the collection. +06. If the body of `response` is not a Json document, it is an error. - > If you receive a `Collection` instead of an `OrderedCollection`, - > you are probably looking at a topics listing. - > You will need to choose a topic from the `items` and then fetch it - > to receive the list of statuses. +Assuming the U·R·L you were given was valid, you will end this + algorithm with a Json‐L·D response, and you can use the `@type` + attribute to determine the response type. +`@type` will be either a string or an array. + + + If the `@type` is or contains `Forum`, the resource is a collection + of topics. + + + If the `@type` is or contains `Thread`, the resource is a + collection of statuses. + + + If the `@type` is or contains `Microblog`, the resource describes + this site as a whole. + The `streams` property will contain a list of available `Forum`s + and `Thread`s, as objects with an `@id` and `@type`. + +The items in the collection (`Forum` or `Thread`) may be determined + through one of the following methods :— + + + If the `@type` is or contains `CollectionPage` or + `OrderedCollectionPage`, then its `items` will contain resources. + This is a partial collection, and the `prev` and `next` properties + can be used to access further items from the parent collection + (indicated by `partOf`). + `first` and `current`, in this scenario, point “horizontally” to + the first and latest pages of items, not to subpages. + + + If the `@type` is or contains `Collection` or `OrderedCollection` + and the resource has `first` and/or `current` properties, then + the `items` property will not be present. + `first` and `current` can be accessed to provide + `OrderedCollectionPage`s listing the items of the collection. + + + Otherwise, the `items` property will contain every item in the + collection. Statuses themselves have the following properties :— + **`@id`**: The identifier of the status. + + **`@type`**: + The value `MicroblogPost`. + + **`created`** [`dcterms:created`]: The creation date for the status, as an `xsd:dateTime`. @@ -277,5 +377,8 @@ Statuses themselves have the following properties :— + **`subject`** [`dcterms:subject`] (optional): The topic of the status, for topic statuses. + + **`title`** [`dcterms:title`] (optional): + The title of the status. + + **`content`** [`sioc:content`]: The content of the status, as an `rdf:XMLLiteral`.