.. program:: jetstream server

.. _structure-server-info:

:index:`Server Information Structure`
-------------------------------------

A Server Information structure is returned from :meth:`~jetstream.serverinterface.ServerInterface.getServerInfo`.

.. glossary::
   :sorted:

   :index:`allowRemoteControl <pair: Server Information Structure; allowRemoteControl>`
      This indicates whether the server accepts API connections from remote hosts. If this is false, API connections are only accepted from *localhost*.

   :index:`apiControlPort <pair: Server Information Structure; apiControlPort>`
      The port number on which the server will accept API connections.

   :index:`apiVersion <pair: Server Information Structure; apiVersion>`
      The API compatibility version for the connected server. API methods are aware of the server version required, and will report an error if the API versions do not match.

   :index:`authRequired <pair: Server Information Structure; authRequired>`
      This indicates whether this server requires authentication for API connections. If ``True`` then you must call either :meth:`~jetstream.serverinterface.ServerInterface.auth` or :meth:`~jetstream.serverinterface.ServerInterface.authAsync` after calling :meth:`~jetstream.apiinterface.APIInterface.connect`.

   :index:`bandwidthLimits <pair: Server Information Structure; bandwidthLimits>`
      :ref:`structure-server-info-bandwidth-limits`

   :index:`certificateValidation <pair: Server Information Structure; certificateValidation>`
      Number of days remaining until SSL certificate expiry.

   :index:`configuration <pair: Server Information Structure; configuration>`
      :ref:`structure-server-info-configuration`. Note that this key only exists for superusers. See :meth:`~jetstream.serverinterface.ServerInterface.superuser`.

   :index:`encryptionAvailable <pair: Server Information Structure; encryptionAvailable>`
      This indicates whether this server supports encrypted connections.

   :index:`eventLogAvailable <pair: Server Information Structure; eventLogAvailable>`
      This indicates whether the server's event log is active. If active, the ``getEventLog`` command may be used to retrieve the server's event history.

   :index:`hostName <pair: Server Information Structure; hostName>`
      The name of the machine host that is running the server. This is different from the ``serverName``, which is assigned to the JetStream server itself.

   :index:`license <pair: Server Information Structure; license>`
      :ref:`structure-server-info-license`

   :index:`multiplexAvailable <pair: Server Information Structure; multiplexAvailable>`
      This indicates whether the same port number can be used for both the sending and receiving traffic. If multiplex is not supported, unique ports must be used for each.

   :index:`publicKey <pair: Server Information Structure; publicKey>`
      A server's public key, used for encrypted connections.

   :index:`minCipher <pair: Server Information Structure; minCipher>`
      A server's minimum supported transfer cipher.

   :index:`receiver <pair: Server Information Structure; receiver>`
      :ref:`structure-server-info-receiver`

   :index:`revision <pair: Server Information Structure; revision>`
      An integer representing revision (version) of the server.

   :index:`serverExternalAddress <pair: Server Information Structure; serverExternalAddress>`
      Hostname and port, as specified by the :option:`--external-address` option at server start.

   :index:`serverId <pair: Server Information Structure; serverId>`
      A string that uniquely identifies a server instance. This ID is regenerated every time a server is launched.

   :index:`serverName <pair: Server Information Structure; serverName>`
      A friendly name assigned to a server.

   :index:`serverPlatform <pair: Server Information Structure; serverPlatform>`
      A string that represents the OS running the server. One of ``windows``, ``linux``, or ``macOS``.

   :index:`serverTime <pair: Server Information Structure; serverTime>`
      A timestamp indicating the current time on this server. See :doc:`/api/timestamps`.

   :index:`serverUid <pair: Server Information Structure; serverUid>`
      A string that uniquely identifies a server. This ID is generated once, and stored in the server's persistent state.

   :index:`sharedTokensAvailable <pair: Server Information Structure; sharedTokensAvailable>`
      This indicates whether the server supports creation and use of shared tokens. See :meth:`~jetstream.sendinterface.SendInterface.createSharedToken`.

   :index:`APITokensAvailable <pair: Server Information Structure; APITokensAvailable>`
      This indicates whether the server supports creation and use of API tokens. See :meth:`~jetstream.serverinterface.ServerInterface.createAPIToken`.

   :index:`user <pair: Server Information Structure; user>`
      :ref:`structure-server-info-user`

   :index:`version <pair: Server Information Structure; version>`
      A string representing the version of the server.


.. versionchanged:: 1.5.0 Added `version` and `revision` keys.
.. versionchanged:: 1.6.0 Added `bandwidthLimits`.
.. versionchanged:: 1.7.0 Added `certificateValidation`.
.. versionchanged:: 2.4.0 Added `APITokensAvailable`.


.. _structure-server-info-receiver:

:index:`Receiver Server Information Structure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Receiver Server Information structure is returned as part of the :ref:`structure-server-info`.

.. glossary::
   :sorted:

   :index:`authRequired <pair: Receiver Server Information Structure; authRequired>`
      ``True`` if the server required a username and password for transfers.

   :index:`encryptionEnabled <pair: Receiver Server Information Structure; encryptionEnabled>`
      ``True`` if the server has encryption enabled. If encryption is enabled, transfers can only be initiated to a server which also has encryption enabled.

   :index:`onlyAuthorizedClientsAllowed <pair: Receiver Server Information Structure; onlyAuthorizedClientsAllowed>`
      Indicates whether this receiving server allows only pre-authenticated clients. Clients may be pre-authenticated using the :meth:`~jetstream.recvinterface.RecvInterface.addAuthorizedClientAsync` command.

   :index:`receiverIP <pair: Receiver Server Information Structure; receiverIP>`
      The IP for the receiver connection. An IP of *0.0.0.0* is a wildcard that means the server is listening for connections from any IP.

   :index:`receiverPort <pair: Receiver Server Information Structure; receiverPort>`
      The port for the receiver connection.

   :index:`relayIP <pair: Receiver Server Information Structure; relayIP>`
      The IP for the relay server, if using a relay. Will be ``None`` if not using a relay.

   :index:`relayPort <pair: Receiver Server Information Structure; relayPort>`
      The port for the relay server, if using a relay. Will be ``None`` if not using a relay.

   :index:`socketSendBufferSize <pair: Receiver Server Information Structure; socketSendBufferSize>`
      The size of the buffer allocated for sending data.

   :index:`socketRecvBufferSize <pair: Receiver Server Information Structure; socketRecvBufferSize>`
      The size of the buffer allocated for receiving data.


.. _structure-server-info-bandwidth-limits:

:index:`Server Bandwidth Limits Structure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Bandwidth Limits structure is returned as part of the :ref:`structure-server-info`.

.. glossary::
   :sorted:

   :index:`incomingLimitActive <pair: Server Configuration Structure; incomingLimitActive>`
      Whether incoming limits are applied.

   :index:`incomingRateLimit <pair: Server Configuration Structure; incomingRateLimit>`
      The maximum incoming data rate, in kilobits-per-second.

   :index:`incomingMaxConnections <pair: Server Configuration Structure; incomingMaxConnections>`
      The maximum number of incoming connections.

   :index:`outgoingLimitActive <pair: Server Configuration Structure; outgoingLimitActive>`
      Whether outgoing limits are applied.

   :index:`outgoingRateLimit <pair: Server Configuration Structure; outgoingRateLimit>`
      The maximum outgoing data rate, in kilobits-per-second.

   :index:`borrowIncoming <pair: Server Configuration Structure; borrowIncoming>`
      If both incoming and outgoing rate limits are active, add unused incoming bandwidth to the outgoing rate limit.

   :index:`borrowOutgoing <pair: Server Configuration Structure; borrowOutgoing>`
      If both incoming and outgoing rate limits are active, add unused outgoing bandwidth to the incoming rate limit.



.. _structure-server-info-configuration:

:index:`Server Configuration Structure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Configuration structure is returned as part of the :ref:`structure-server-info`. It holds data about how the server is configured and is only available to a superuser. See :meth:`~jetstream.serverinterface.ServerInterface.superuser`.

.. glossary::
   :sorted:

   :index:`persistentStateDir <pair: Server Configuration Structure; persistentStateDir>`
      The path to which the server will save its encryption key files. If this directory is specified at launch, the server will provide a consistent public key for its encryption interfaces.

   :index:`triggersAvailable <pair: Server Configuration Structure; triggersAvailable>`
      This indicates whether the server's trigger system is active. If active, any triggers found in the ``triggersDir`` will be executed in response to their associated events.

   :index:`garbageCollect <pair: Server Configuration Structure; garbageCollect>`
      :ref:`structure-server-info-configuration-garbagecollect`

   :index:`cloudFileCache <pair: Server Configuration Structure; cloudFileCache>`
      :ref:`structure-server-info-configuration-cloudfilecache`

.. versionchanged:: 1.8.0 Added `fileCache` and `garbageCollect` keys.
.. versionchanged:: 2.6.0 Renamed `fileCache` to `cloudFileCache`.

.. _structure-server-info-configuration-cloudfilecache:

:index:`Cloud File Cache Structure`
***********************************

A Cloud File Cache structure is returned as part of the :ref:`structure-server-info-configuration`. It holds the server's cloud file cache information.

.. glossary::
   :sorted:

   :index:`highWatermark <pair: Cloud File Cache Structure; highWatermark>`
      The size, in bytes, of memory allocated to cloud file cache.

   :index:`maximumSize <pair: Cloud File Cache Structure; maximumSize>`
      Maximum size, in bytes, of the cloud file cache. This can be defined at server startup using :option:`--max-cloud-cache-size`


.. _structure-server-info-configuration-garbagecollect:

:index:`Garbage Collection Structure`
***************************************************

A Garbage Collection structure is returned as part of the :ref:`structure-server-info-configuration`. It holds the server's garbage collection configuration.

.. glossary::
   :sorted:

   :index:`intervalSeconds <pair: Garbage Collection Structure; intervalSeconds>`
      The time, in seconds, between each garbage collection.

   :index:`timeLimitSeconds <pair: Garbage Collection Structure; timeLimitSeconds>`
      The grace period, in seconds, to allow for items that are ready to be garbage collected.

.. seealso::
   * :meth:`~jetstream.serverinterface.ServerInterface.updateGarbageCollectSettings`


.. _structure-server-info-license:

:index:`Server License Structure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A License structure is returned as part of the :ref:`structure-server-info`.

.. glossary::
   :sorted:

   :index:`errorMessage <pair: Server License Structure; errorMessage>`
      If a license is invalid, a message indicating the reason.

   :index:`expiry <pair: Server License Structure; expiry>`
      The date on which the JetStream license expires for this server.

   :index:`valid <pair: Server License Structure; valid>`
      This indicates whether the license is currently valid (``True``) or invalid (``False``).


.. _structure-server-info-user:

:index:`Server User Structure`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A User structure is returned as part of the :ref:`structure-server-info`.

.. glossary::
   :sorted:

   :index:`authed <pair: Server User Structure; authed>`
      This indicates whether authentication has been performed on the current API connection.

   :index:`superuser <pair: Server User Structure; superuser>`
      This indicates whether the authenticated user is a superuser. If not authenticated, this will be ``False``.

   :index:`token <pair: Server User Structure; token>`
      The token of the currently authenticated user. If not authenticated or user name auth was used, this will be ``None``.

   :index:`tokenSession <pair: Server User Structure; tokenSession>`
      The token session of the currently authenticated user. If not authenticated or user name auth was used, this will be ``None``.

   :index:`userName <pair: Server User Structure; userName>`
      The name of the currently authenticated user. If not authenticated or if token auth was used, this will be ``None``.

   :index:`sandboxed <pair: Server User Structure; sandboxed>`
      This indicates whether the user is restricted to a sandbox directory, instead of full filesystem access. Returns ``None`` when not authenticated.

   :index:`permissions <pair: Server User Structure; permissions>`
      Permissions granted to this user. See :data:`~jetstream.constants.PERMISSIONS`

.. versionchanged:: 1.5.0 Renamed `username` to `userName`.
.. versionchanged:: 2.4.0 Added `permissions`.

