From 3433657ccf3e2c24090a13af873b237d0db171b5 Mon Sep 17 00:00:00 2001 From: Goffi Date: Sun, 26 Sep 2021 16:35:49 +0200 Subject: [PATCH 1/3] jp (common): add neovim (`nvim`) default arguments --- sat_frontends/jp/common.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sat_frontends/jp/common.py b/sat_frontends/jp/common.py index 7c9ecc6e..6f462ba6 100644 --- a/sat_frontends/jp/common.py +++ b/sat_frontends/jp/common.py @@ -36,11 +36,12 @@ from sat.tools import config from configparser import NoSectionError, NoOptionError from collections import namedtuple -# defaut arguments used for some known editors (editing with metadata) +# default arguments used for some known editors (editing with metadata) VIM_SPLIT_ARGS = "-c 'set nospr|vsplit|wincmd w|next|wincmd w'" EMACS_SPLIT_ARGS = '--eval "(split-window-horizontally)"' EDITOR_ARGS_MAGIC = { "vim": VIM_SPLIT_ARGS + " {content_file} {metadata_file}", + "nvim": VIM_SPLIT_ARGS + " {content_file} {metadata_file}", "gvim": VIM_SPLIT_ARGS + " --nofork {content_file} {metadata_file}", "emacs": EMACS_SPLIT_ARGS + " {content_file} {metadata_file}", "xemacs": EMACS_SPLIT_ARGS + " {content_file} {metadata_file}", From 31985ed0fc7cb60ca59240051b4a13ebf29c7079 Mon Sep 17 00:00:00 2001 From: Goffi Date: Sun, 26 Sep 2021 16:35:56 +0200 Subject: [PATCH 2/3] component (file-sharing): use `file-sharing` instead of `file_sharing`: a dash is used instead of underscore for entry-point and config section., as it is best practice to use dash on command-line. --- sat/plugins/plugin_comp_file_sharing.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/sat/plugins/plugin_comp_file_sharing.py b/sat/plugins/plugin_comp_file_sharing.py index 2309fef1..27c40de9 100644 --- a/sat/plugins/plugin_comp_file_sharing.py +++ b/sat/plugins/plugin_comp_file_sharing.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 -# SAT plugin for parrot mode (experimental) +# Libervia File Sharing component # Copyright (C) 2009-2021 Jérôme Poisson (goffi@goffi.org) # This program is free software: you can redistribute it and/or modify @@ -48,7 +48,7 @@ log = getLogger(__name__) PLUGIN_INFO = { C.PI_NAME: "File sharing component", - C.PI_IMPORT_NAME: "file_sharing", + C.PI_IMPORT_NAME: "file-sharing", C.PI_MODES: [C.PLUG_MODE_COMPONENT], C.PI_TYPE: C.PLUG_TYPE_ENTRY_POINT, C.PI_PROTOCOLS: [], @@ -207,7 +207,7 @@ class HTTPFileServer(resource.Resource): request.content = None # the 2 following headers are not standard, but useful in the context of file - # sharing with HTTP Upload: first one allow uploaded to specify the path + # sharing with HTTP Upload: first one allow uploader to specify the path # and second one will disable public exposure of the file through HTTP path = request.getHeader("Xmpp-File-Path") if path: @@ -243,7 +243,7 @@ class FileSharingRequest(server.Request): @property def upload_data(self): - """A tuple with upload_id and filename retrieve from requested path""" + """A tuple with upload_id and filename retrieved from requested path""" if self._upload_data is not None: return self._upload_data @@ -369,9 +369,9 @@ class FileSharing: self._getDirectoryMetadataElts) self.files_path = self.host.getLocalPath(None, C.FILES_DIR, profile=False) self.http_port = int(self.host.memory.getConfig( - 'component file_sharing', 'http_upload_port', 8888)) + 'component file-sharing', 'http_upload_port', 8888)) connection_type = self.host.memory.getConfig( - 'component file_sharing', 'http_upload_connection_type', 'https') + 'component file-sharing', 'http_upload_connection_type', 'https') if connection_type not in ('http', 'https'): raise exceptions.ConfigError( 'bad http_upload_connection_type, you must use one of "http" or "https"' @@ -382,7 +382,7 @@ class FileSharing: reactor.listenTCP(self.http_port, self.server) else: options = tls.getOptionsFromConfig( - self.host.memory.config, "component file_sharing") + self.host.memory.config, "component file-sharing") tls.TLSOptionsCheck(options) context_factory = tls.getTLSContextFactory(options) reactor.listenSSL(self.http_port, self.server, context_factory) @@ -393,7 +393,7 @@ class FileSharing: def profileConnecting(self, client): self.init() public_base_url = self.host.memory.getConfig( - 'component file_sharing', 'http_upload_public_facing_url') + 'component file-sharing', 'http_upload_public_facing_url') if public_base_url is None: client._file_sharing_base_url = f"https://{client.host}:{self.http_port}" else: @@ -409,7 +409,7 @@ class FileSharing: def getQuota(self, client, entity): """Return maximum size allowed for all files for entity""" # TODO: handle special entities like admins - quotas = self.host.memory.getConfig("component file_sharing", "quotas_json", {}) + quotas = self.host.memory.getConfig("component file-sharing", "quotas_json", {}) entity_bare_s = entity.userhost() try: quota = quotas["jids"][entity_bare_s] From 8c9af32d560d6dce82f4a0b806d4c98d39f1e639 Mon Sep 17 00:00:00 2001 From: Goffi Date: Sun, 26 Sep 2021 16:38:00 +0200 Subject: [PATCH 3/3] doc: components documentation: rel 362 --- doc/components.rst | 153 +++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + doc/libervia-cli/profile.rst | 1 + 3 files changed, 155 insertions(+) create mode 100644 doc/components.rst diff --git a/doc/components.rst b/doc/components.rst new file mode 100644 index 00000000..2dec1bda --- /dev/null +++ b/doc/components.rst @@ -0,0 +1,153 @@ +.. _components: + +=================== +Libervia Components +=================== + +Libervia can act as an XMPP server component, which can be seen as a generic plugin for +XMPP servers. + +This page explains which components are available and how to use them. + +Running a component +=================== + +Components are linked to a Libervia profile in the same way as normal clients. + +To run a component, you'll need to know its *entry point*, which is the name of the import +name of plugin managing it. The entry point to use will be specified in the component +installation documentation. + +You'll also have to declare the component on your XMPP server, this is a server dependent +step and you'll have to check your server documentation for details. You'll have to +specify a **shared secret** (can also be named simply *password*) that must be set both on +the XMPP server and as the XMPP password of the Libervia profile. + +Here is a list of relevant documentation for most common servers: + +ejabberd + https://docs.ejabberd.im/admin/configuration/listen-options/ + +MongooseIm + https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice + +OpenFire + use the web-based admin panel + +Prosody + https://prosody.im/doc/components + +Tigase + https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html + + +On Libervia, setup is done with Libervia CLI's :ref:`profile create ` +command. + +You'll usually want to have the component to start automatically when the backend +is started, for this you must unset the profile password (not to be confused with the XMPP +password which is the one also set on the server configuration) with ``-p ""`` and set +auto-connection with ``-A``. + +You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology) +with ``-x `` and the JID to use with ``-j +.``. + +The component entry point is specified with ``-C ``. + +.. _XEP-0144: https://xmpp.org/extensions/xep-0114.html + +example +------- + +Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID +``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to +start automatically with the backend, thus she doesn't set a profile password. The +entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same +name for the profile. To do this, she enters the following command:: + + $ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A + +The component will then be started next time Libervia Backend is launched. If Louise +wants to connect it immediately, she can use:: + + $ li profile connect -cp ap-gateway + +Available Components +==================== + +Below is a list of currently available components in Libervia, and instructions on what +they do and how to use them. + + +File Sharing +------------ + +**entry_point:** ``file-sharing`` + +File Sharing component manage the hosting of user files. Users can upload file there using +either `Jingle File Transfer`_ or `HTTP File Upload`_. + +There is no limit to the size of files which can be uploaded, but administrators can set a +quota to limit the space that can be used. + +Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_. + +Files can be shared with a public HTTP link, or made available only to a specified list of +entities (JIDs). Permissions can be set through Ad-Hoc Commands. + +.. _Jingle File Transfer: https://xmpp.org/extensions/ +.. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html +.. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html +.. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html + +Configuration +~~~~~~~~~~~~~ + +All options are to be set in ``[component file-sharing]`` section. + +``http_upload_port`` + port to use for HTTP File Upload + + **default**: 8888 + +``http_upload_connection_type`` + either ``http`` or ``https``. + + **default**: ``https`` + + Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to + be used only if you use a HTTP server as a proxy, and this server is already set for + TLS. + +``http_upload_public_facing_url`` + must be set to the URL that end-user will see. Notably useful if the component is behind + a proxy. + + **default**: ``https://: