Diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_muc_http_defaults/README.markdown	Fri Feb 19 16:01:41 2021 +0100
@@ -0,0 +1,141 @@
+---
+summary: Seed MUC configuration from JSON REST API
+---
+
+# Introduction
+
+This module fetches configuration for MUC rooms from an API when rooms
+are created.
+
+# Requirements
+
+Prosody **trunk** required.
+
+# Configuration
+
+`muc_create_api_url`
+:   URL template for the API endpoint to get settings. `{room.jid}` is
+    replaced by the address of the room in question.
+
+`muc_create_api_auth`
+:   The value of the Authorization header to authenticate against the
+    API. E.g. `"Bearer /rXU4tkQTYQMgdHfMLH6"`{.lua}
+
+## Example
+
+``` {.lua}
+Component "channels.example.net" "muc"
+modules_enabled = { "muc_http_defaults" }
+muc_create_api_url = "https://api.example.net/muc/config?jid={room.jid}"
+```
+
+# API
+
+A RESTful JSON API is used. Any error causes the room to be destroyed.
+
+The returned JSON consists of two main parts, the room configuration and
+the affiliations (member list).
+
+## Schema
+
+Here's a JSON Schema in YAML format describing the expected JSON
+response data:
+
+``` {.yaml}
+---
+type: object
+properties:
+  config:
+    type: object
+    properties:
+      name: string
+      description: string
+      language: string
+      persistent: boolean
+      public: boolean
+      members_only: boolean
+      allow_member_invites: boolean
+      public_jids: boolean
+      subject: string
+      changesubject: boolean
+      historylength: integer
+      moderated: boolean
+      archiving: boolean
+  affiliations:
+    anyOf:
+    - type: array
+      items:
+        type: object
+        required:
+        - jid
+        - affiliation
+        properties:
+          jid:
+            type: string
+            pattern: ^[^@/]+@[^/]+$
+          affiliation:
+            ref: '#/definitions/affiliation'
+          nick: string
+    - type: object
+      patternProperties:
+        ^[^@/]+@[^/]+$: '#/definitions/affiliation'
+definitions:
+  affiliation:
+    type: string
+    enum:
+    - owner
+    - admin
+    - member
+    - none
+    - outcast
+...
+```
+
+## Example
+
+A basic example with some config settings and a few affiliations:
+
+``` {.json}
+GET /muc/config?jid=place@channels.example.net
+Accept: application/json
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+   "affiliations" : [
+      {
+         "affiliation" : "owner",
+         "jid" : "bosmang@example.net",
+         "nick" : "bosmang"
+      },
+      {
+         "affiliation" : "admin",
+         "jid" : "xo@example.net",
+         "nick" : "xo"
+      },
+      {
+         "affiliation" : "member",
+         "jid" : "john@example.net"
+      }
+   ],
+   "config" : {
+      "archiving" : true,
+      "description" : "This is the place",
+      "members_only" : true,
+      "moderated" : false,
+      "name" : "The Place",
+      "persistent" : true,
+      "public" : false,
+      "subject" : "Discussions regarding The Place"
+   }
+}
+```
+
+To allow the creation without making any changes, letting whoever
+created it be the owner, just return an empty JSON object:
+
+    HTTP/1.1 200 OK
+    Content-Type: application/json
+
+    {}