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