Where Do Transfers Go?
======================

.. program:: jetstream server

The path to which transferred files are written is determined by three variables:

    1. The receiving server's sandbox path or system root;
    2. A per-transfer destination path; and,
    3. Each file's target path.

The path of a file written by the JetStream receiver is then: :file:`/<receiver_sandbox_path>/<transfer_path>/<file_target_path>`.

By default, a JetStream server is not sandboxed, and defaults to writing transfers directly below the system's root folder. Transfers can be restricted to one or more directories by setting up :doc:`/sandboxing/index`.

The per-transfer destination path is specified when creating a transfer with :py:meth:`~jetstream.sendinterface.SendInterface.createTransfer`.

Finally, each file's target path is specified as part of the ``fileMappings`` option with :meth:`~jetstream.sendinterface.SendInterface.createManifest`.

.. table:: Destination path mapping summary

   =================  ================  ======================  ================================================
   Sandbox Directory  Destination Path  File Target Path        Full Path
   =================  ================  ======================  ================================================
   *<None>*           *<None>*          ``/mnt/data/file.txt``  ``/mnt/data/file.txt``
   *<None>*           *<None>*          ``file.txt``            ``/file.txt``
   ``/storage``       *<None>*          ``/mnt/data/file.txt``  ``/storage/mnt/data/file.txt``
   ``/storage``       ``/repository1``  ``/mnt/data/file.txt``  ``/storage/repository1/mnt/data/file.txt``
   ``/storage/%u``    *<None>*          ``/mnt/data/file.txt``  ``/storage/<username>/mnt/data/file.txt``
   ``/storage/%u``    ``/repository1``  ``/mnt/data/file.txt``  ``/storage/<username>/repository/mnt/data/file.txt``
   =================  ================  ======================  ================================================

Example:
    In this example, no server sandbox has been specified, so the transfer alone will specify the path created on the receiving server.

    Here, the :command:`jscp` command is used to initiate a transfer. No transfer destination path is specified.

    .. code-block:: none

        jscp /source/my_file jetstream02.lan:/target/my_file

    The file at the receiving server will be written to :file:`/target/my_file`, dictated entirely by the file's target path..

Example:
    In this example, the receiving server was started with :option:`--sandbox-dir` set to ``/storage``, and thus sandboxes all transfers below this folder.

    Again, the :command:`jscp` command is used to initiate a transfer. No transfer destination path is specified.

    .. code-block:: none

        jscp /source/my_file jetstream02.lan:/target/my_file

    The file at the receiving server will be written to :file:`/storage/target/my_file`, combining the server's sandbox and the file's target path..

Example:
    Again, the receiving server was with started its sandbox specified as :file:`/storage`.

    The :command:`jscp` command is used to initiate a transfer. This time, the path :file:`/project` is specified as the destination path for all files in the transfer.

    .. code-block:: none

        jscp -d /project /source/my_file jetstream02.lan:/target/my_file

    The file at the receiving server will be written to :file:`/storage/project/target/my_file`, combining the server's sandbox, the transfer's destination path, and the file's target path.

Example:
    This example replicates the transfer above, but uses the command line API instead of the :command:`jscp` command.

    .. code-block:: bash

        $ jetstream api createDestination --destinationAddress=jetstream02.lan --sendRateMax=1500000
        $ jetstream api createManifest --fileMappings /source/my_file:/target/my_file
        $ jetstream api createTransfer --destinationId <destinationId> --manifestId <manifestId> --destinationPath /project

    If the receiving server has been sandboxed below :file:`/storage` then the file will be written to :file:`/storage/project/target/my_file`, combining the server's sandbox, the transfer's destination path, and the file's target path.

    If the receiving server has not been sandboxed, then the file will be written to :file:`/project/target/my_file`, combining the transfer's destination path, and the file's target path.
