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

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