WebSocket API

WebSocket API

.gitignore

@@ -1,6 +1,7 @@
 build-x64/
 build-x86/
 chocolatey/tools/chocolateyinstall.ps1
+docs/build
 src/core/version_info.cpp
 tools/Cake
 tools/Cake.CMake

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "libs/websocketpp"]
+	path = libs/websocketpp
+	url = https://github.com/zaphoyd/websocketpp

CMakeLists.txt

@@ -94,6 +94,7 @@ set(PICOTORRENT_SOURCES
     src/client/ui/property_sheets/preferences/connection_page
     src/client/ui/property_sheets/preferences/downloads_page
     src/client/ui/property_sheets/preferences/general_page
+    src/client/ui/property_sheets/preferences/remote_page
     src/client/ui/file_dialog_callback
     src/client/ui/main_window
     src/client/ui/notify_icon
@@ -107,6 +108,20 @@ set(PICOTORRENT_SOURCES
     src/client/ui/taskbar_list
     src/client/ui/torrent_context_menu
     src/client/ui/torrent_drop_target
+
+    # Security
+    src/client/security/certificate_manager
+    src/client/security/dh_params
+    src/client/security/random_string_generator
+
+    # WebSocket server
+    src/client/ws/websocket_server
+    src/client/ws/messages/pico_state_message
+    src/client/ws/messages/torrent_added_message
+    src/client/ws/messages/torrent_finished_message
+    src/client/ws/messages/torrent_removed_message
+    src/client/ws/messages/torrent_updated_message
+    src/client/ws/serialization/torrent_serializer
 )
 
 if(WIN32)
@@ -128,6 +143,7 @@ endif()
 
 include_directories(
     include/
+    libs/websocketpp
     tools/PicoTorrent.Libs/include
 )
 
@@ -145,6 +161,7 @@ add_definitions(
 # WIN32 definitions
 if(WIN32)
     add_definitions(
+        -D_SCL_SECURE_NO_WARNINGS
         -D_UNICODE
         -D_WIN32
         -D_WIN32_WINNT=0x0600

README.md

@@ -33,6 +33,7 @@ To successfully build PicoTorrent, you need the following tools installed,
 Build PicoTorrent by running the following in a PowerShell prompt,
 
 ```
+PS> git submodule update --init
 PS> .\build.ps1
 ```
 

appveyor.yml

@@ -9,6 +9,9 @@ environment:
    - platform: x86
    - platform: x64
 
+install:
+  - git submodule update --init
+
 # Build script
 build_script:
 - powershell -NoProfile -ExecutionPolicy unrestricted -Command .\build.ps1 -Platform %platform%

docs/make.bat

@@ -0,0 +1,40 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+    set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set SRCDIR=src
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %SRCDIR%
+set I18NSPHINXOPTS=%SPHINXOPTS% %SRCDIR%
+if NOT "%PAPER%" == "" (
+    set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+    set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+    :help
+    echo.Please use `make ^<target^>` where ^<target^> is one of
+    echo.  html       to make standalone HTML files
+    goto end
+)
+
+if "%1" == "clean" (
+    for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+    del /q /s %BUILDDIR%\*
+    goto end
+)
+
+if "%1" == "html" (
+    %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+    if errorlevel 1 exit /b 1
+    echo.
+    echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+    goto end
+)
+
+:end

docs/src/conf.py

@@ -0,0 +1,46 @@
+import os
+import re
+import sys
+
+
+def get_picotorrent_version():
+    with open('../../VERSION') as f:
+        return f.read()
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('sphinx-plugins'))
+
+# -- General configuration ------------------------------------------------
+
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'PicoTorrent'
+copyright = u'Viktor Elofsson and contributors'
+
+version = get_picotorrent_version()
+release = version
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ----------------------------------------------
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['static']

docs/src/index.rst

@@ -0,0 +1,17 @@
+PicoTorrent
+===========
+
+Overview
+--------
+
+PicoTorrent is a tiny BitTorrent client for Windows. It is written in C++ using
+Rasterbar-libtorrent and the raw Win32 API.
+
+.. note:: In case you find errors in this documentation you can help by sending
+          `pull requests <https://github.com/picotorrent/picotorrent>`_!
+
+
+.. toctree::
+   :maxdepth: 2
+
+   websocket-api/index

docs/src/websocket-api/index.rst

@@ -0,0 +1,65 @@
+The WebSocket API
+=================
+
+PicoTorrent features an embedded WebSocket API which pushes events to connected
+clients in real time. This is different from most other BitTorrent client APIs
+since you do not need to poll for changes.
+
+
+.. note:: All examples shown here assumes a default configuration.
+
+
+Configuring the WebSocket
+-------------------------
+
+To enable the WebSocket API, go to
+:menuselection:`View --> Preferences --> Remote`. From here you can also
+change the listen port as well as view certificate information and
+authentication token.
+
+
+Connecting
+----------
+
+The WebSocket is listening for connections on :file:`wss://localhost:7676/`.
+This is an *SSL* protected endpoint, and PicoTorrent will generate a
+self-signed certificate upon first launch. This certificate is not trusted and
+may throw warnings.
+
+To successfully connect, you will need the authentication token which is
+randomly generated upon first launch. You can get this from the
+:file:`PicoTorrent.json` configuration file, or by navigating to
+:menuselection:`View --> Preferences --> Remote` in the application.
+
+The authentication token must be passed in the header `X-PicoTorrent-Token`,
+otherwise the connection *will* fail.
+
+
+Messages
+--------
+
+The message API is JSON based and each message contains the `type` hash which
+tells the consumer what type of message it is.
+
+The first message sent is the `pico_state` message, which contains the full
+state for PicoTorrent.
+
+.. toctree::
+   :maxdepth: 1
+
+   pico_state <messages/pico_state_message>
+   torrent_added <messages/torrent_added_message>
+   torrent_finished <messages/torrent_finished_message>
+   torrent_removed <messages/torrent_removed_message>
+   torrent_updated <messages/torrent_updated_message>
+
+
+Objects
+-------
+
+Each message may contain one or more well-documented objects.
+
+.. toctree::
+   :maxdepth: 1
+
+   torrent <objects/torrent>

docs/src/websocket-api/messages/pico_state_message.rst

@@ -0,0 +1,34 @@
+The `pico_state` message
+========================
+
+The `pico_state` message is sent when a client connection is opened and
+contains the full PicoTorrent state (all managed torrents) as well as some
+version information.
+
+
+Example
+-------
+
+.. code-block:: javascript
+   :linenos:
+
+   {
+     "type": "pico_state",
+
+     "version_info": {
+       // The WebSocket API version.
+       "api_version": 1,
+
+       // The name of the Git branch PicoTorrent was built from.
+       "git_branch": "master",
+
+       // The Git commit hash (short form) of the build.
+       "git_commit_hash": "<sha1 hash of commit>",
+
+       // The PicoTorrent version.
+       "picotorrent_version": "x.y.z"
+     },
+
+     // An array of torrent objects managed by PicoTorrent.
+     "torrents": [ ... ]
+   }

docs/src/websocket-api/messages/torrent_added_message.rst

@@ -0,0 +1,19 @@
+The `torrent_added` message
+===========================
+
+The `torrent_added` message is sent when a torrent is successfully added to the
+session and contains a `torrent` object representing the newly added torrent.
+
+
+Example
+-------
+
+.. code-block:: javascript
+   :linenos:
+
+   {
+     "type": "torrent_added",
+
+     // A torrent object representing the added torrent.
+     "torrent": { ... }
+   }

docs/src/websocket-api/messages/torrent_finished_message.rst

@@ -0,0 +1,19 @@
+The `torrent_finished` message
+==============================
+
+The `torrent_finished` message is sent when all non-skipped files of a torrent
+has finished downloading.
+
+
+Example
+-------
+
+.. code-block:: javascript
+   :linenos:
+
+   {
+     "type": "torrent_finished",
+
+     // A torrent object representing the finished torrent.
+     "torrent": { ... }
+   }