Lady’s Gitweb - x_status_git/blob - README.markdown

   1 # Status.git
   2
   3 A minimal git‐based self‐hosted status publishing solution.
   4
   5 ## What It Is
   6
   7  +  A Python script, `post-receive`, suitable for use as a post‐receive
   8       Git hook, which generates a number of `.jsonld` files from a
   9       source repository of text posts.
  10
  11  +  A small collection of H·T·M·L files designed to display the
  12       generated `.jsonld` in a human‐readable fashion.
  13
  14 ## What It Is Not
  15
  16  +  A server or server configuration (you will need to supply these
  17       yourself; see below).
  18
  19  +  Suitable for deployment on a simple filesystem server like
  20       NeoCities or GitHub Pages (it requires both Git hooks and H·T·T·P
  21       routing).
  22
  23  +  Interactive in any way (i·e “social media”).
  24
  25  +  Compatible with the ActivityPub fediverse (or any other push‐based
  26       social media platform).
  27
  28 ## Script Configuration
  29
  30 You will need to edit the `post-receive` script to adjust the following
  31   constants to match your setup :—
  32
  33  +  **`GIT_DIRECTORY`**:
  34     The absolute path to this Git repository on your server.
  35     It is expected that this will be a bare repository (ending in
  36       `.git`).
  37
  38  +  **`BUILD_DIRECTORY`**:
  39     In order to access the files when you push, the repository will be
  40       checked out here.
  41     **This directory will be deleted on every push.**
  42
  43  +  **`PUBLIC_DIRECTORY`**:
  44     The directory that your server serves files from.
  45     **This directory will be deleted on every push,** so if you need to
  46       serve additional files (i·e those not generated by this script),
  47       you should place those files in a different directory and adjust
  48       your server configuration accordingly.
  49     Note that the `post-receive` script and associted H·T·M·L files
  50       provided by this repository expect a certain server configuration
  51       described below.
  52
  53   +  **`PUBLIC_URL`**:
  54      The U·R·L that you are serving your site from (with no trailing
  55        slash).
  56      You cannot serve Status.git from a subdirectory.
  57
  58 A `Makefile` is provided to make installing the `post-receive` script
  59   on your server easy (assuming you have `ssh` access).
  60 You’ll need to supply some variables there, too :—
  61
  62  +  **`USERNAME`**:
  63     Your SSH username.
  64
  65  +  **`DOMAIN`**:
  66     The domain or other address of your site.
  67
  68  +  **`GIT_REPOSITORY`**:
  69     The absolute path to this Git repository, as above.
  70
  71 ## Server Configuration
  72
  73 Your server should be configured to serve the following files from the
  74   provided `PUBLIC_DIRECTORY` in response to the following requests :—
  75
  76 ### H·T·M·L responses
  77
  78 These responses **must** be served with a `Content-Type` of
  79   `text/html;charset=UTF-8` (or equivalent).
  80 Note that these paths **do not** have a trailing slash.
  81
  82  +  **`GET /`**:
  83     Serve the file at `/index.html`.
  84
  85  +  **`GET /statuses`**:
  86     Serve the file at `/.statuses.html`.
  87     A `Link` header with the value
  88       `</statuses.jsonld>;rel=meta;type="application/ld+json"` (or
  89       equivalent) **must** be provided.
  90
  91  +  **`GET /$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
  92     Serve the file at `/.topic.html`.
  93     A `Link` header with the value
  94       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
  95       equivalent) **must** be provided.
  96
  97  +  **`GET /$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
  98     Serve the file at `/.status.html`.
  99     A `Link` header with the value
 100       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
 101       equivalent) **must** be provided.
 102
 103  +  **`GET /topics`**:
 104     Serve the file at `/.topics.html`.
 105     A `Link` header with the value
 106       `</topics.jsonld>;rel=meta;type="application/ld+json"` (or
 107       equivalent) **must** be provided.
 108
 109  +  **`GET /topics/$TOPIC`** (where `$TOPIC` matches `[0-9A-Za-z_-]+`):
 110     Serve the file at `/.topic.html`.
 111     A `Link` header with the value
 112       `</$TOPIC.jsonld>;rel=meta;type="application/ld+json"` (or
 113       equivalent) **must** be provided.
 114
 115  +  **`GET /topics/$TOPIC/*`** (where `$TOPIC` matches
 116       `[0-9A-Za-z_-]+`):
 117     Serve the file at `/.status.html`.
 118     A `Link` header with the value
 119       `</$TOPIC.jsonld>;rel=meta;type="application/ld+json"` (or
 120       equivalent) **must** be provided.
 121
 122 ### Json‐L·D responses
 123
 124 These responses **should** be served with a `Content-Type` of
 125   `application/ld+json`.
 126 In all cases, for `/$PATH.jsonld`, this just serves the file at
 127   `/$PATH/index.jsonld`.
 128
 129  +  **`GET /statuses.jsonld`**:
 130     Serve the file at `/statuses/index.jsonld`.
 131
 132  +  **`GET /$YYYY-MM.jsonld`** (where `$YYYY-MM` is an
 133       `xsd:gYearMonth`):
 134     Serve the file at `/$YYYY-MM/index.jsonld`.
 135
 136  +  **`GET /topics.jsonld`**:
 137     Serve the file at `/topics/index.jsonld`.
 138
 139  +  **`GET /topics/$TOPIC.jsonld`** (where `$TOPIC` matches
 140       `[0-9A-Za-z_-]+`):
 141     Serve the file at `/topics/$TOPIC/index.jsonld`.
 142
 143 ### Other Headers
 144
 145 All responses **should** have a `Access-Control-Allow-Origin` header
 146   with a value of `*` (assuming your server does not use credentials
 147   and is not being served behind a firewall).
 148
 149 ## Committing Statuses To Git
 150
 151 The `post-receive` script will run whenever you make a commit to the
 152   `live` branch, which should be set as your default.
 153 Statuses are represented by a small collection of files committed to
 154   particular locations in this repository :—
 155
 156  +  Files committed to `/YYYY/MM/DD/HH.MM.SSZ/` (the final component
 157       can actually take any form but a time is **recommended**) are
 158       ordinary statuses.
 159
 160  +  Files committed to `/topic/TOPICNAME/a/b/c/d/xxxx` (where `a`, `b`,
 161       `c`, and `d` are lowercase hexadecimal digits and `xxxx` can be
 162       anything) is a status posted to a specific topic (`TOPICNAME`).
 163     It is **recommended** that you make `a/b/c/d` the first four digits
 164       of an MD5 hash of the status content and `xxxx` the remaining
 165       digits (security is not an issue here, so MD5 is fine).
 166     `TOPICNAME` should have the form `[0-9A-Za-z_-]+`.
 167
 168 The intent is that “ordinary statuses” are a bit more ephemeral whereas
 169   “topic statuses” can serve as reference material.
 170 Using an MD5 hash for topic statuses ensures you don’t post the same
 171   thing twice.
 172
 173 The files which represent a status are as follows :—
 174
 175  +  **`text`**:
 176     The text of the status.
 177     Blank lines separate paragraphs; linebreaks will be preserved.
 178     There is a special markup for links: `<https://link.example>`, or
 179       `<https://link.example>="link text"` if you want to supply link
 180       text.
 181     At present, no other markup is supported.
 182
 183  +  **`0=x_status_git_1.0`**:
 184     This file is **optional** and not currently used for anything, but
 185       indicates that the post follows the `1.0` format.
 186     The contents of this file, if present, **must** be
 187       `x_status_git_1.0`, optionally followed by a trailing newline.
 188
 189  +  **`1=NAME`** (where `NAME` might be anything):
 190     This file is **recommended** and indicates the author of the
 191       status.
 192     Only one author is currently supported.
 193     The value of `NAME` **must** give the name of the author of the
 194       status.
 195     The contents of this file **must** give the author’s URL,
 196       optionally followed by a trailing newline.
 197
 198  +  **`3=YYYY-MM-DD`** (where `YYYY-MM-DD` is a date):
 199     This file is **required** and indicates the date of the status.
 200     Only one date is currently supported.
 201     The value of `YYYY-MM-DD` **should** give the date of the status,
 202       although this is not used (in favour of the full timestamp).
 203     The contents of this file **must** give the full `xsd:dateTime`
 204       timestamp of the status, optionally followed by a trailing
 205       newline.
 206
 207  +  **`4=IDENTIFIER`** (where `IDENTIFIER` might be anything):
 208     This file is **required** and provides an identifier for the
 209       status.
 210     Only one identifier is currently supported.
 211     The contents of this file **must** be an I·R·I which uniquely
 212       identifies the status (for example, a U·U·I·D or `tag:` URI).
 213     The value of `IDENTIFIER` **must** be a locally‐unique identifier
 214       for the status and **should** resemble the contents where
 215       possible.
 216     (Note, however, that `IDENTIFIER` cannot contain slashes and need
 217       not be a valid I·R·I.)
 218
 219 Files with names that begin with the strings `2=` or `x_status_git_`
 220   are reserved for backwards‐compatible extensions.
 221
 222 Status.git has no opinion on how these files make their way into the
 223   Git repository, except that all the files for a single status should
 224   be added in the same commit.
 225 The intention is that the simple nature of these files will make them
 226   easy to automate.
 227
 228 ## I Am Computer, How Do I Get Status?
 229
 230 Assume you are given a U·R·L `resource_url` which you think points to
 231   some kind of Status.git resource.
 232 Start by resolving it as follows :—
 233
 234 01. Make a `HEAD` request to `resource_url`.
 235
 236 02. If there is a `Link` header with a `rel` of `meta` and a `type` of
 237       `application/ld+json`, set `resource_url` to the URL provided in
 238       that header and restart these steps from step 1.
 239
 240 03. Make a `GET` request to `resource_url` and let `response` be the
 241       response.
 242
 243 04. Set `document` as follows :—
 244
 245     01. If the `Content-Type` header of `response` has a type of `text`
 246           and subtype of `html`, let `document` be the result of
 247           processing the body of `response` into a D·O·M tree as an
 248           H·T·M·L document .
 249         It is an error if this process fails.
 250
 251     02. If the `Content-Type` header of `response` has a type of
 252           `application` and a subtype which is `xml` or which ends in
 253           `+xml`, let `document` be the result of processing the body
 254           of `response` into a D·O·M tree as an X·M·L document .
 255         It is an error if this process fails.
 256
 257     03. Otherwise, let `document` be null.
 258
 259 05. If `document` is not null :—
 260
 261     01. If there is a `<link>` element in either the H·T·M·L namespace
 262           or the Atom namespace in `document` with a `rel` of `meta`
 263           and a `type` of `application/ld+json`, set `resource_url` to
 264           the `href` of that `<link>` element and restart these steps
 265           from step 1.
 266         If multiple such elements exist, choose the first one.
 267
 268     02. Otherwise, it is an error.
 269
 270 06. If the body of `response` is not a Json document, it is an error.
 271
 272 Assuming the U·R·L you were given was valid, you will end this
 273   algorithm with a Json‐L·D response, and you can use the `@type`
 274   attribute to determine the response type.
 275 `@type` will be either a string or an array.
 276
 277  +  If the `@type` is or contains `Forum`, the resource is a collection
 278       of topics.
 279
 280  +  If the `@type` is or contains `Thread`, the resource is a
 281       collection of statuses.
 282
 283 The items in the collection may be determined through one of the
 284   following methods :—
 285
 286  +  If the `@type` is or contains `OrderedCollectionPage`, then its
 287       `items` will be an array of resources.
 288     This is a partial collection, and the `prev` and `next` properties
 289       can be used to access further items from the parent collection
 290       (indicated by `partOf`).
 291
 292  +  If the `@type` is or contains `OrderedCollection`, and the resource
 293       has `first` and `current` properties, then the `items` property
 294       will not be present.
 295     `first` and `current` can be accessed to provide
 296       `OrderedCollectionPage`s listing the items of the collection as
 297       above.
 298
 299  +  Otherwise, the `items` property will contain every item in the
 300       collection.
 301
 302 Statuses themselves have the following properties :—
 303
 304  +  **`@id`**:
 305     The identifier of the status.
 306
 307  +  **`@type`**:
 308     The value `MicroblogPost`.
 309
 310  +  **`created`** [`dcterms:created`]:
 311     The creation date for the status, as an `xsd:dateTime`.
 312
 313  +  **`creator`** [`dcterms:creator`] (optional):
 314     The author of the status, as an object with an `@id` and `name`
 315       [`foaf:name`].
 316
 317  +  **`identifier`** [`dcterms:identifier`]:
 318     An I·R·I which uniquely identifies the status.
 319     This differs from the `@id` in that it is not expected to be
 320       dereferenceable.
 321
 322  +  **`subject`** [`dcterms:subject`] (optional):
 323     The topic of the status, for topic statuses.
 324
 325  +  **`content`** [`sioc:content`]:
 326     The content of the status, as an `rdf:XMLLiteral`.