view mod_muc_http_defaults/README.markdown @ 4876:0f5f2d4475b9

mod_http_xep227: Add support for import via APIs rather than direct store manipulation In particular this transitions PEP nodes and data to be imported via mod_pep's APIs, fixing issues with importing at runtime while PEP data may already be live in RAM. Next obvious candidate for this approach is rosters, so clients get immediate roster pushes and other special handling (such as emitting subscribes to reach the desired subscription state).
author Matthew Wild <mwild1@gmail.com>
date Tue, 18 Jan 2022 17:01:18 +0000
parents e11abf578df5
children
line wrap: on
line source

---
summary: Seed MUC configuration from JSON REST API
---

# Introduction

This module fetches configuration for MUC rooms from an API when rooms
are created.

# Requirements

Should work with Prosody 0.11.

# 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}

In the URL template variable, the room JID is available as `{room.jid}`,
which would be turned into `room@muc.host`. To only get the room
localpart, `{room.jid|jid_node}` can be used, and `{room.jid|jid_host}`
splits out the `muc.host` part.

## 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).

## Room Configuration

The top level `config` field contains a map of properties corresponding
to the fields in the room configuration dialog, named similarly to the
[room configuration default][doc:modules:mod_muc#room-configuration-defaults] in
Prosodys config file.

| Property               | Type    | Description                                                               |
|------------------------|---------|---------------------------------------------------------------------------|
| `name`                 | string  | Name of the chat                                                          |
| `description`          | string  | Longer description of the chat                                            |
| `language`             | string  | Language code                                                             |
| `persistent`           | boolean | Whether the room should keep existing if it becomes empty                 |
| `public`               | boolean | `true` to include in public listing                                       |
| `members_only`         | boolean | Membership or open                                                        |
| `allow_member_invites` | boolean | If members can invite others into members-only rooms                      |
| `public_jids`          | boolean | If everyone or only moderators should see real identities                 |
| `subject`              | string  | In-room subject or topic message                                          |
| `changesubject`        | boolean | If `true` then everyone can change the subject, otherwise only moderators |
| `historylength`        | integer | Number of messages to keep in memory (legacy method)                      |
| `moderated`            | boolean | New participants start without voice privileges if set to `true`          |
| `archiving`            | boolean | Whether [archiving][doc:modules:mod_muc_mam] is enabled                   |

## Affiliations

The list of members go in `affiliations` which is either an object
mapping addresses to affiliations (e.g. `{"user@host":"admin"}`{.json}),
or it can be an array of address, affiliation and optionally a reserved
nickname (e.g.
`[{"jid":"user@host","affiliation":"member","nick":"joe"}]`{.json}).

## Schema

Here's a JSON Schema in YAML format describing the expected JSON
response data:

``` {.yaml}
---
type: object
properties:
  config:
    type: object
    properties:
      name:
        type: string
      description:
        type: string
      language:
        type: string
      persistent:
        type: boolean
      public:
        type: boolean
      members_only:
        type: boolean
      allow_member_invites:
        type: boolean
      public_jids:
        type: boolean
      subject:
        type: string
      changesubject:
        type: boolean
      historylength:
        type: integer
      moderated:
        type: boolean
      archiving:
        type: boolean
  affiliations:
    oneOf:
    - type: array
      items:
        type: object
        required:
        - jid
        - affiliation
        properties:
          jid:
            type: string
            pattern: ^[^@/]+@[^/]+$
          affiliation:
            $ref: '#/definitions/affiliation'
          nick:
            type: string
    - type: object
      additionalProperties:
        $ref: '#/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

    {}