Adding upstream version 2.1.2~dev0+20240219.upstream/2.1.2_dev0+20240219upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 178 insertions, 0 deletions

diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst
new file mode 100644
index 0000000..75673af
--- /dev/null
+++ b/docs/source/reference/api.rst
@@ -0,0 +1,14 @@
+Deluge RPC API
+==============
+
+* :doc:`rpc`
+
+.. autoclass:: deluge.core.core.Core
+    :members:
+    :exported:
+    :noindex:
+
+.. autoclass:: deluge.core.daemon.Daemon
+    :members:
+    :exported:
+    :noindex:
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
new file mode 100644
index 0000000..a6dea3a
--- /dev/null
+++ b/docs/source/reference/index.rst
@@ -0,0 +1,11 @@
+Reference
+=========
+
+Technical reference material.
+
+.. toctree::
+
+    Web UI <web>
+    Deluge RPC <rpc>
+    RPC API <api>
+    Web API <webapi>
diff --git a/docs/source/reference/rpc.rst b/docs/source/reference/rpc.rst
new file mode 100644
index 0000000..7454bd2
--- /dev/null
+++ b/docs/source/reference/rpc.rst
@@ -0,0 +1,98 @@
+Deluge RPC
+==========
+---------------
+Message Formats
+---------------
+DelugeRPC is a protocol used for daemon/client communication. There are four
+types of messages involved in the protocol: RPC Request, RPC Response,
+RPC Error and Event. All messages are zlib compressed with rencode encoded strings
+and their data formats are detailed below.
+
+"""""""""""
+RPC Request
+"""""""""""
+This message is created and sent by the client to the server requesting that a
+remote method be called. Multiple requests can be bundled in a list.
+
+**[[request_id, method, [args], {kwargs}], ...]**
+
+**request_id** (int)
+    An integer determined by the client that is used in replies from the server.
+    This is used to ensure the client knows which request the data is in
+    response to. Another alternative would be to respond in the same order the
+    requests come in, but this could cause lag if an earlier request takes
+    longer to process.
+
+**method** (str)
+    The name of the remote method to call. This name can be in dotted format to
+    call other objects or plugins methods.
+
+**args** (list)
+    The arguments to call the method with.
+
+**kwargs** (dict)
+    The keyword arguments to call the method with.
+
+""""""""""""
+RPC Response
+""""""""""""
+This message is created and sent in response to a RPC Request from a client. It
+will hold the return value of the requested method call. In the case of an
+error, a RPC Error message will be sent instead.
+
+**[message_type, request_id, [return_value]]**
+
+**message_type** (int)
+    This will be a RPC_RESPONSE type id. This is used on the client side to
+    determine what kind of message is being received from the daemon.
+
+**request_id** (int)
+    The request_id is the same as the one sent by the client in the initial
+    request. It used on the client side to determine what message this is in
+    response to.
+
+**return_value** (list)
+    The return value of the method call.
+
+"""""""""
+RPC Error
+"""""""""
+This message is created in response to an error generated while processing a
+RPC Request and will serve as a replacement for a RPC Response message.
+
+**[message_type, request_id, exception_type, exception_msg, traceback]**
+
+**message_type** (int)
+    This will be a RPC_ERROR type id.
+
+**request_id** (int)
+    The request_id is the same as the one sent by the client in the initial
+    request.
+
+**exception_type** (str)
+    The type of exception raised.
+
+**exception_msg** (str)
+    The message as to why the exception was raised.
+
+**traceback** (str)
+    The traceback of the generated exception.
+
+"""""
+Event
+"""""
+This message is created by the daemon and sent to the clients without being in
+response to a RPC Request. Events are generally sent for changes in the
+daemon's state that the clients need to be made aware of.
+
+**[message_type, event_name, data]**
+
+**message_type** (int)
+    This will be a RPC_EVENT type id.
+
+**event_name** (str)
+    This is the name of the event being emitted by the daemon.
+
+**data** (list)
+    Additional data to be sent with the event. This is dependent upon the event
+    being emitted.
diff --git a/docs/source/reference/web.md b/docs/source/reference/web.md
new file mode 100644
index 0000000..f0471ce
--- /dev/null
+++ b/docs/source/reference/web.md
@@ -0,0 +1,38 @@
+# Deluge Web UI
+
+The Deluge web interface is a full featured interface built using the ExtJS framework,
+running on top of a Twisted web server.
+
+## SSL Configuration
+
+By default the web interface will use the same private key and certificate as
+the Deluge daemon. You can use a different certificate/key and specify it in the Web UI
+config, see below for details.
+
+### Create SSL Certificate Examples
+
+Sample guide: [How to Create a SSL Certificate][ssl cert]
+
+#### Linux
+
+    openssl req -new -x509 -nodes -out deluge.cert.pem -keyout deluge.key.pem
+
+#### Windows
+
+    C:\OpenSSL\bin\openssl.exe req -config C:\OpenSSL\bin\openssl.cnf -x509 -days 365 -newkey rsa:1024 -keyout hostkey.pem -nodes -out hostcert.pem
+
+### Enable Web UI SSL
+
+There are two ways to enable SSL encryption in the web server:
+
+- Specify in your config (accessible via the Preferences window).
+- Use `--ssl` when running the web server, overriding the configuration value to enable SSL.
+
+## Enable Development mode
+
+Append `?dev=true` to the Web UI URL to enable development mode, uses the source
+JavaScript files (if available) rather than compressed versions:
+
+    http://127.0.0.1:8112/?dev=true
+
+[ssl cert]: http://www.yatblog.com/2007/02/27/how-to-create-a-ssl-certificate/
diff --git a/docs/source/reference/webapi.rst b/docs/source/reference/webapi.rst
new file mode 100644
index 0000000..56aadfc
--- /dev/null
+++ b/docs/source/reference/webapi.rst
@@ -0,0 +1,17 @@
+Deluge Web JSON-RPC API
+=======================
+
+* Spec: `JSON-RPC v1 <https://www.jsonrpc.org/specification_v1>`_
+* URL: ``/json``
+* :doc:`api`
+
+
+.. autoclass:: deluge.ui.web.json_api.WebApi
+    :members:
+    :exported:
+    :noindex:
+
+.. autoclass:: deluge.ui.web.json_api.WebUtils
+    :members:
+    :exported:
+    :noindex: