# HG changeset patch # User Kim Alvefur # Date 1613746901 -3600 # Node ID 07aa101a1ae79e0b8788a1cb471578682691b4a4 # Parent 3d593b612e07172be0a52c99e709e148a6d8563d mod_muc_http_defaults: Get MUC room config from an API diff -r 3d593b612e07 -r 07aa101a1ae7 mod_muc_http_defaults/README.markdown --- /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 + + {} diff -r 3d593b612e07 -r 07aa101a1ae7 mod_muc_http_defaults/mod_muc_http_defaults.lua --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_http_defaults/mod_muc_http_defaults.lua Fri Feb 19 16:01:41 2021 +0100 @@ -0,0 +1,142 @@ +-- Copyright (C) 2021 Kim Alvefur +-- +-- This file is MIT licensed. Please see the +-- COPYING file in the source package for more information. +-- + +local http = require "net.http"; +local httperr = require "net.http.errors"; +local async = require "util.async"; +local errors = require "util.error"; +local uh = require "util.http"; +local jid = require "util.jid"; +local json = require "util.json"; +local st = require "util.stanza"; + +local render = require "util.interpolation".new("%b{}", uh.urlencode); + +module:depends"muc"; + +local url_template = assert(module:get_option_string("muc_create_api_url", nil), "'muc_create_api_url' is a required option"); +local apiauth = module:get_option_string("muc_create_api_auth", nil); + +local ex = { + headers = { + accept = "application/json"; + authorization = apiauth; + } +}; + +local function check_status(response) + if math.floor(response.code/100) > 2 then + error(httperr.new(response.code, response.body)); + end + return response; +end + +local problems = errors.init(module.name, { + format = { type = "cancel", condition = "internal-server-error", text = "API server returned invalid data, see logs" }, + config = { type = "cancel", condition = "internal-server-error", text = "A problem occured while creating the room, see logs" }, +}); + +local function get_json(response) + return assert(json.decode(response.body), problems.new("format")); +end + +local function apply_config(room, settings) + local affiliations = settings.affiliations; + if type(affiliations) == "table" then + + -- COMPAT the room creator is unconditionally made 'owner' + -- clear existing affiliation + for existing_affiliation in pairs(room._affiliation) do + room:set_affiliation(true, existing_affiliation, "none"); + end + + if affiliations[1] ~= nil then -- array of ( jid, affiliation, nick ) + for _, aff in ipairs(affiliations) do + if type(aff) == "table" and type(aff.jid) == "string" and (aff.nick == nil or type(aff.nick) == "string") then + local prepped_jid = jid.prep(aff.jid); + if prepped_jid then + local ok, err = room:set_affiliation(true, prepped_jid, aff.affiliation, aff.nick and { nick = aff.nick }); + if not ok then + module:log("error", "Could not set affiliation in %s: %s", room.jid, err); + return nil, problems.new("config"); + end + else + module:log("error", "Invalid JID returned from API for %s: %q", room.jid, aff.jid); + return nil, problems.new("format"); + end + else + module:log("error", "Invalid affiliation item returned from API for %s: %q", room.jid, aff); + return nil, problems.new("format"); + end + end + else -- map of jid : affiliation + for user_jid, aff in pairs(affiliations) do + if type(user_jid) == "string" and type(aff) == "string" then + local prepped_jid = jid.prep(user_jid); + if prepped_jid then + local ok, err = room:set_affiliation(true, prepped_jid, aff); + if not ok then + module:log("error", "Could not set affiliation in %s: %s", room.jid, err); + return nil, problems.new("config"); + end + else + module:log("error", "Invalid JID returned from API: %q", aff.jid); + return nil, problems.new("format"); + end + end + end + end + elseif affiliations ~= nil then + module:log("error", "Invalid affiliations returned from API for %s: %q", room.jid, affiliations); + return nil, problems.new("format", { field = "affiliations" }); + end + + local config = settings.config; + if type(config) == "table" then + -- TODO reject invalid fields instead of ignoring them + if type(config.name) == "string" then room:set_name(config.name); end + if type(config.description) == "string" then room:set_description(config.description); end + if type(config.language) == "string" then room:set_language(config.language); end + if type(config.password) == "string" then room:set_password(config.password); end + if type(config.subject) == "string" then room:set_subject(config.subject); end + + if type(config.public) == "boolean" then room:set_public(config.public); end + if type(config.members_only) == "boolean" then room:set_members_only(config.members_only); end + if type(config.allow_member_invites) == "boolean" then room:set_allow_member_invites(config.allow_member_invites); end + if type(config.moderated) == "boolean" then room:set_moderated(config.moderated); end + if type(config.persistent) == "boolean" then room:set_persistent(config.persistent); end + if type(config.changesubject) == "boolean" then room:set_changesubject(config.changesubject); end + + if type(config.historylength) == "number" then room:set_historylength(config.historylength); end + if type(config.public_jids) == "boolean" then room:set_whois(config.public_jids and "anyone" or "moderators"); end + -- Leaving out presence_broadcast for now + + -- mod_muc_mam + if type(config.archiving) == "boolean" then room._config.archiving = config.archiving; end + elseif config ~= nil then + module:log("error", "Invalid config returned from API for %s: %q", room.jid, config); + return nil, problems.new("format", { field = "config" }); + end + return true; +end + +module:hook("muc-room-pre-create", function(event) + local url = render(url_template, event); + module:log("debug", "Calling API at %q for room %s", url, event.room.jid); + local ret, err = errors.coerce(async.wait_for(http.request(url, ex):next(check_status):next(get_json))); + if not ret then + event.room:destroy(); + event.origin.send(st.error_reply(event.stanza, err)); + return true; + end + + local configured, err = apply_config(event.room, ret); + if not configured then + event.room:destroy(); + event.origin.send(st.error_reply(event.stanza, err)); + return true; + end +end, -2);