merge bookmark @

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 <li_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 <your_shared_secret>`` and the JID to use with ``-j
+<component_subdomain>.<server.tld>``.
+
+The component entry point is specified with ``-C <entry_point>``.
+
+.. _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://<component host>:<http_upload_port``
+
+``quotas_json``
+  a JSON object indicating quotas to use for users. The object can have 3 keys:
+
+  ``admins``
+    quotas to use for administrators (i.e. profiles set in ``admins_list``)
+
+  ``users``
+    quotas to use for normal users (i.e. non admin profiles)
+
+  ``jids``
+    per-jid specific quotas. The value is a JSON object where key is a user bare jid and
+    value is a quota.
+
+  Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and
+  binary prefixes`_ can be used).
+
+  example::
+
+    quotas_json = {
+      "admins": null,
+      "users": "50 Mio",
+      "jids": {"pierre@example.org": "1 Gio"}
+    }
+
+  .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples

doc/index.rst

@@ -26,6 +26,7 @@ You can follow this documentation to learn more on it, or join our official XMPP
    installation.rst
    overview.rst
    configuration.rst
+   components.rst
    developer.rst
    /libervia-cli/index.rst
    /libervia-tui/index.rst

doc/libervia-cli/profile.rst

@@ -41,6 +41,7 @@ Disconnect the profile ``pierre``::
 
   $ li profile disconnect -p pierre
 
+.. _li_profile_create:
 
 create
 ======

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
@@ -49,7 +49,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: [],
@@ -208,7 +208,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:
@@ -244,7 +244,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
 
@@ -370,9 +370,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"'
@@ -383,7 +383,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)
@@ -394,7 +394,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:
@@ -410,7 +410,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]

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}",