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     A `Link` header with the value
  85       `</about.jsonld>;rel=meta;type="application/ld+json"` (or
  86       equivalent) **must** be provided.
  87
  88  +  **`GET /about`**:
  89     Serve the file at `/.about.html`.
  90     A `Link` header with the value
  91       `</about.jsonld>;rel=meta;type="application/ld+json"` (or
  92       equivalent) **must** be provided.
  93
  94  +  **`GET /statuses`**:
  95     Serve the file at `/.statuses.html`.
  96     A `Link` header with the value
  97       `</statuses.jsonld>;rel=meta;type="application/ld+json"` (or
  98       equivalent) **must** be provided.
  99
 100  +  **`GET /$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
 101     Serve the file at `/.topic.html`.
 102     A `Link` header with the value
 103       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
 104       equivalent) **must** be provided.
 105
 106  +  **`GET /$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
 107     Serve the file at `/.status.html`.
 108     A `Link` header with the value
 109       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
 110       equivalent) **must** be provided.
 111
 112  +  **`GET /topics`**:
 113     Serve the file at `/.topics.html`.
 114     A `Link` header with the value
 115       `</topics.jsonld>;rel=meta;type="application/ld+json"` (or
 116       equivalent) **must** be provided.
 117
 118  +  **`GET /topics/$TOPIC`** (where `$TOPIC` matches `[0-9A-Za-z_-]+`):
 119     Serve the file at `/.topic.html`.
 120     A `Link` header with the value
 121       `</$TOPIC.jsonld>;rel=meta;type="application/ld+json"` (or
 122       equivalent) **must** be provided.
 123
 124  +  **`GET /topics/$TOPIC/*`** (where `$TOPIC` matches
 125       `[0-9A-Za-z_-]+`):
 126     Serve the file at `/.status.html`.
 127     A `Link` header with the value
 128       `</$TOPIC.jsonld>;rel=meta;type="application/ld+json"` (or
 129       equivalent) **must** be provided.
 130
 131 ### Json‐L·D responses
 132
 133 These responses **should** be served with a `Content-Type` of
 134   `application/ld+json`.
 135 In all cases, for `/$PATH.jsonld`, this just serves the file at
 136   `/$PATH/index.jsonld`.
 137
 138  +  **`GET /about.jsonld`**:
 139     Serve the file at `/about/index.jsonld`.
 140
 141  +  **`GET /statuses.jsonld`**:
 142     Serve the file at `/statuses/index.jsonld`.
 143
 144  +  **`GET /$YYYY-MM.jsonld`** (where `$YYYY-MM` is an
 145       `xsd:gYearMonth`):
 146     Serve the file at `/$YYYY-MM/index.jsonld`.
 147
 148  +  **`GET /topics.jsonld`**:
 149     Serve the file at `/topics/index.jsonld`.
 150
 151  +  **`GET /topics/$TOPIC.jsonld`** (where `$TOPIC` matches
 152       `[0-9A-Za-z_-]+`):
 153     Serve the file at `/topics/$TOPIC/index.jsonld`.
 154
 155 ### Other Headers
 156
 157 All responses **should** have a `Access-Control-Allow-Origin` header
 158   with a value of `*` (assuming your server does not use credentials
 159   and is not being served behind a firewall).
 160
 161 ## Committing Statuses To Git
 162
 163 The `post-receive` script will run whenever you make a commit to the
 164   `live` branch, which should be set as your default.
 165 Statuses are represented by a small collection of files committed to
 166   particular locations in this repository :—
 167
 168  +  Files committed to `/YYYY/MM/DD/HH.MM.SSZ/` (the final component
 169       can actually take any form but a time is **recommended**) are
 170       ordinary statuses.
 171
 172  +  Files committed to `/topic/TOPICNAME/a/b/c/d/xxxx` (where `a`, `b`,
 173       `c`, and `d` are lowercase hexadecimal digits and `xxxx` can be
 174       anything) is a status posted to a specific topic (`TOPICNAME`).
 175     It is **recommended** that you make `a/b/c/d` the first four digits
 176       of an MD5 hash of the status content and `xxxx` the remaining
 177       digits (security is not an issue here, so MD5 is fine).
 178     `TOPICNAME` should have the form `[0-9A-Za-z_-]+`.
 179
 180 The intent is that “ordinary statuses” are a bit more ephemeral whereas
 181   “topic statuses” can serve as reference material.
 182 Using an MD5 hash for topic statuses ensures you don’t post the same
 183   thing twice.
 184
 185 The files which represent a status are as follows :—
 186
 187  +  **`text`**:
 188     The text of the status.
 189     Blank lines separate paragraphs; linebreaks will be preserved.
 190     There is a special markup for links: `<https://link.example>`, or
 191       `<https://link.example>="link text"` if you want to supply link
 192       text.
 193     At present, no other markup is supported.
 194
 195  +  **`0=x_status_git_1.0`**:
 196     This file is **optional** and not currently used for anything, but
 197       indicates that the post follows the `1.0` format.
 198     The contents of this file, if present, **must** be
 199       `x_status_git_1.0`, optionally followed by a trailing newline.
 200
 201  +  **`1=NAME`** (where `NAME` might be anything):
 202     This file is **recommended** and indicates the author of the
 203       status.
 204     Only one author is currently supported.
 205     The value of `NAME` **must** give the name of the author of the
 206       status.
 207     The contents of this file **must** give the author’s URL,
 208       optionally followed by a trailing newline.
 209
 210  +  **`3=YYYY-MM-DD`** (where `YYYY-MM-DD` is a date):
 211     This file is **required** and indicates the date of the status.
 212     Only one date is currently supported.
 213     The value of `YYYY-MM-DD` **should** give the date of the status,
 214       although this is not used (in favour of the full timestamp).
 215     The contents of this file **must** give the full `xsd:dateTime`
 216       timestamp of the status, optionally followed by a trailing
 217       newline.
 218
 219  +  **`4=IDENTIFIER`** (where `IDENTIFIER` might be anything):
 220     This file is **required** and provides an identifier for the
 221       status.
 222     Only one identifier is currently supported.
 223     The contents of this file **must** be an I·R·I which uniquely
 224       identifies the status (for example, a U·U·I·D or `tag:` URI).
 225     The value of `IDENTIFIER` **must** be a locally‐unique identifier
 226       for the status and **should** resemble the contents where
 227       possible.
 228     (Note, however, that `IDENTIFIER` cannot contain slashes and need
 229       not be a valid I·R·I.)
 230
 231 Files with names that begin with the strings `2=` or `x_status_git_`
 232   are reserved for backwards‐compatible extensions.
 233
 234 Status.git has no opinion on how these files make their way into the
 235   Git repository, except that all the files for a single status should
 236   be added in the same commit.
 237 The intention is that the simple nature of these files will make them
 238   easy to automate.
 239
 240 ## I Am Computer, How Do I Get Status?
 241
 242 Assume you are given a U·R·L `resource_url` which you think points to
 243   some kind of Status.git resource.
 244 Start by resolving it as follows :—
 245
 246 01. Make a `HEAD` request to `resource_url`.
 247
 248 02. If there is a `Link` header with a `rel` of `meta` and a `type` of
 249       `application/ld+json`, set `resource_url` to the URL provided in
 250       that header and restart these steps from step 1.
 251
 252 03. Make a `GET` request to `resource_url` and let `response` be the
 253       response.
 254
 255 04. Set `document` as follows :—
 256
 257     01. If the `Content-Type` header of `response` has a type of `text`
 258           and subtype of `html`, let `document` be the result of
 259           processing the body of `response` into a D·O·M tree as an
 260           H·T·M·L document .
 261         It is an error if this process fails.
 262
 263     02. If the `Content-Type` header of `response` has a type of
 264           `application` and a subtype which is `xml` or which ends in
 265           `+xml`, let `document` be the result of processing the body
 266           of `response` into a D·O·M tree as an X·M·L document .
 267         It is an error if this process fails.
 268
 269     03. Otherwise, let `document` be null.
 270
 271 05. If `document` is not null :—
 272
 273     01. If there is a `<link>` element in either the H·T·M·L namespace
 274           or the Atom namespace in `document` with a `rel` of `meta`
 275           and a `type` of `application/ld+json`, set `resource_url` to
 276           the `href` of that `<link>` element and restart these steps
 277           from step 1.
 278         If multiple such elements exist, choose the first one.
 279
 280     02. Otherwise, it is an error.
 281
 282 06. If the body of `response` is not a Json document, it is an error.
 283
 284 Assuming the U·R·L you were given was valid, you will end this
 285   algorithm with a Json‐L·D response, and you can use the `@type`
 286   attribute to determine the response type.
 287 `@type` will be either a string or an array.
 288
 289  +  If the `@type` is or contains `Forum`, the resource is a collection
 290       of topics.
 291
 292  +  If the `@type` is or contains `Thread`, the resource is a
 293       collection of statuses.
 294
 295  +  If the `@type` is or contains `Microblog`, the resource describes
 296       this site as a whole.
 297     The `streams` property will contain a list of available `Forum`s
 298       and `Thread`s, as objects with an `@id` and `@type`.
 299
 300 The items in the collection (`Forum` or `Thread`) may be determined
 301   through one of the following methods :—
 302
 303  +  If the `@type` is or contains `CollectionPage` or
 304       `OrderedCollectionPage`, then its `items` will contain resources.
 305     This is a partial collection, and the `prev` and `next` properties
 306       can be used to access further items from the parent collection
 307       (indicated by `partOf`).
 308     `first` and `current`, in this scenario, point “horizontally” to
 309       the first and latest pages of items, not to subpages.
 310
 311  +  If the `@type` is or contains `Collection` or `OrderedCollection`
 312       and the resource has `first` and/or `current` properties, then
 313       the `items` property will not be present.
 314     `first` and `current` can be accessed to provide
 315       `OrderedCollectionPage`s listing the items of the collection.
 316
 317  +  Otherwise, the `items` property will contain every item in the
 318       collection.
 319
 320 Statuses themselves have the following properties :—
 321
 322  +  **`@id`**:
 323     The identifier of the status.
 324
 325  +  **`@type`**:
 326     The value `MicroblogPost`.
 327
 328  +  **`created`** [`dcterms:created`]:
 329     The creation date for the status, as an `xsd:dateTime`.
 330
 331  +  **`creator`** [`dcterms:creator`] (optional):
 332     The author of the status, as an object with an `@id` and `name`
 333       [`foaf:name`].
 334
 335  +  **`identifier`** [`dcterms:identifier`]:
 336     An I·R·I which uniquely identifies the status.
 337     This differs from the `@id` in that it is not expected to be
 338       dereferenceable.
 339
 340  +  **`subject`** [`dcterms:subject`] (optional):
 341     The topic of the status, for topic statuses.
 342
 343  +  **`content`** [`sioc:content`]:
 344     The content of the status, as an `rdf:XMLLiteral`.