=doc a first set of new and imported documentation for akka-http

akka-docs-dev/rst/scala/http/directives/coding-directives/compressResponse.rst

@@ -0,0 +1,46 @@
+.. _-compressResponse-:
+
+compressResponse
+================
+
+Uses the first of a given number of encodings that the client accepts. If none are accepted the request
+is rejected with an ``UnacceptedResponseEncodingRejection``.
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: compressResponse
+
+Description
+-----------
+
+The ``compressResponse`` directive allows to specify zero to three encoders to try in the specified order.
+If none are specified the tried list is ``Gzip``, ``Deflate``, and then ``NoEncoding``.
+
+The ``compressResponse()`` directive (without an explicit list of encoders given) will therefore behave as follows:
+
+========================================= ===============================
+``Accept-Encoding`` header                resulting response
+========================================= ===============================
+``Accept-Encoding: gzip``                 compressed with ``Gzip``
+``Accept-Encoding: deflate``              compressed with ``Deflate``
+``Accept-Encoding: deflate, gzip``        compressed with ``Gzip``
+``Accept-Encoding: identity``             uncompressed
+no ``Accept-Encoding`` header present     compressed with ``Gzip``
+========================================= ===============================
+
+For an overview of the different ``compressResponse`` directives see :ref:`WhenToUseWhichCompressResponseDirective`.
+
+Example
+-------
+
+This example shows the behavior of ``compressResponse`` without any encoders specified:
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: compressResponse-0
+
+This example shows the behaviour of ``compressResponse(Gzip)``:
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: compressResponse-1

akka-docs-dev/rst/scala/http/directives/coding-directives/compressResponseIfRequested.rst

@@ -0,0 +1,37 @@
+.. _-compressResponseIfRequested-:
+
+compressResponseIfRequested
+===========================
+
+Only compresses the response when specifically requested by the ``Accept-Encoding`` request header
+(i.e. the default is "no compression").
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: compressResponseIfRequested
+
+Description
+-----------
+
+The ``compressResponseIfRequested`` directive is an alias for ``compressResponse(NoEncoding, Gzip, Deflate)`` and will
+behave as follows:
+
+========================================= ===============================
+``Accept-Encoding`` header                resulting response
+========================================= ===============================
+``Accept-Encoding: gzip``                 compressed with ``Gzip``
+``Accept-Encoding: deflate``              compressed with ``Deflate``
+``Accept-Encoding: deflate, gzip``        compressed with ``Gzip``
+``Accept-Encoding: identity``             uncompressed
+no ``Accept-Encoding`` header present     uncompressed
+========================================= ===============================
+
+For an overview of the different ``compressResponse`` directives see :ref:`WhenToUseWhichCompressResponseDirective`.
+
+Example
+-------
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: compressResponseIfRequested

akka-docs-dev/rst/scala/http/directives/coding-directives/decodeRequest.rst

@@ -0,0 +1,30 @@
+.. _-decodeRequest-:
+
+decodeRequest
+=============
+
+Tries to decode the request with the specified ``Decoder`` or rejects the request with an
+``UnacceptedRequestEncodingRejection(supportedEncoding)``.
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: decodeRequest
+
+Description
+-----------
+
+The ``decodeRequest`` directive is the building block for the ``decompressRequest`` directive.
+
+``decodeRequest`` and ``decompressRequest`` are related like this::
+
+    decompressRequest(Gzip)          = decodeRequest(Gzip)
+    decompressRequest(a, b, c)       = decodeRequest(a) | decodeRequest(b) | decodeRequest(c)
+    decompressRequest()              = decodeRequest(Gzip) | decodeRequest(Deflate) | decodeRequest(NoEncoding)
+
+Example
+-------
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: decodeRequest

akka-docs-dev/rst/scala/http/directives/coding-directives/decompressRequest.rst

@@ -0,0 +1,46 @@
+.. _-decompressRequest-:
+
+decompressRequest
+=================
+
+Decompresses the request if it is can be decoded with one of the given decoders. Otherwise,
+the request is rejected with an ``UnsupportedRequestEncodingRejection(supportedEncoding)``.
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: decompressRequest
+
+Description
+-----------
+
+The ``decompressRequest`` directive allows either to specify a list of decoders or none at all. If
+no ``Decoder`` is specified ``Gzip``, ``Deflate``, or ``NoEncoding`` will be tried.
+
+The ``decompressRequest`` directive will behave as follows:
+
+========================================= ===============================
+``Content-Encoding`` header                resulting request
+========================================= ===============================
+``Content-Encoding: gzip``                 decompressed
+``Content-Encoding: deflate``              decompressed
+``Content-Encoding: identity``             unchanged
+no ``Content-Encoding`` header present     unchanged
+========================================= ===============================
+
+For an overview of the different ``decompressRequest`` directives and which one to use when,
+see :ref:`WhenToUseWhichDecompressRequestDirective`.
+
+Example
+-------
+
+This example shows the behavior of ``decompressRequest()`` without any decoders specified:
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: decompressRequest-0
+
+This example shows the behaviour of ``decompressRequest(Gzip, NoEncoding)``:
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: decompressRequest-1

akka-docs-dev/rst/scala/http/directives/coding-directives/encodeResponse.rst

@@ -0,0 +1,38 @@
+.. _-encodeResponse-:
+
+encodeResponse
+==============
+
+Tries to encode the response with the specified ``Encoder`` or rejects the request with an
+``UnacceptedResponseEncodingRejection(supportedEncodings)``.
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: encodeResponse
+
+Description
+-----------
+
+The directive automatically applies the ``autoChunkFileBytes`` directive as well to avoid having to load
+an entire file into JVM heap.
+
+The parameter to the directive is either just an ``Encoder`` or all of an ``Encoder``, a threshold, and a
+chunk size to configure the automatically applied ``autoChunkFileBytes`` directive.
+
+The ``encodeResponse`` directive is the building block for the ``compressResponse`` and
+``compressResponseIfRequested`` directives.
+
+``encodeResponse``, ``compressResponse``, and ``compressResponseIfRequested`` are related like this::
+
+    compressResponse(Gzip)          = encodeResponse(Gzip)
+    compressResponse(a, b, c)       = encodeResponse(a) | encodeResponse(b) | encodeResponse(c)
+    compressResponse()              = encodeResponse(Gzip) | encodeResponse(Deflate) | encodeResponse(NoEncoding)
+    compressResponseIfRequested()   = encodeResponse(NoEncoding) | encodeResponse(Gzip) | encodeResponse(Deflate)
+
+Example
+-------
+
+.. includecode2:: ../../../code/docs/http/server/directives/CodingDirectivesExamplesSpec.scala
+   :snippet: encodeResponse

akka-docs-dev/rst/scala/http/directives/coding-directives/index.rst

@@ -0,0 +1,64 @@
+.. _CodingDirectives:
+
+CodingDirectives
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   compressResponse
+   compressResponseIfRequested
+   decodeRequest
+   decompressRequest
+   encodeResponse
+   requestEncodedWith
+   responseEncodingAccepted
+
+.. _WhenToUseWhichCompressResponseDirective:
+
+When to use which compression directive?
+----------------------------------------
+
+There are three different directives for performing response compressing with slightly different behavior:
+
+:ref:`-encodeResponse-`
+  Always compresses the response with the one given encoding, rejects the request with an
+  ``UnacceptedResponseEncodingRejection`` if the client doesn't accept the given encoding. The other
+  compression directives are built upon this one. See its description for an overview how they
+  relate exactly.
+
+:ref:`-compressResponse-`
+  Uses the first of a given number of encodings that the client accepts. If none are accepted the request
+  is rejected.
+
+:ref:`-compressResponseIfRequested-`
+  Only compresses the response when specifically requested by the
+  ``Accept-Encoding`` request header (i.e. the default is "no compression").
+
+See the individual directives for more detailed usage examples.
+
+.. _WhenToUseWhichDecompressRequestDirective:
+
+When to use which decompression directive?
+------------------------------------------
+
+There are two different directives for performing request decompressing with slightly different behavior:
+
+:ref:`-decodeRequest-`
+  Attempts to decompress the request using **the one given decoder**, rejects the request with an
+  ``UnsupportedRequestEncodingRejection`` if the request is not encoded with the given encoder.
+
+:ref:`-decompressRequest-`
+  Decompresses the request if it is encoded with **one of the given encoders**.
+  If the request's encoding doesn't match one of the given encoders it is rejected.
+
+
+Combining compression and decompression
+---------------------------------------
+
+As with all Spray directives, the above single directives can be combined
+using ``&`` to produce compound directives that will decompress requests and
+compress responses in whatever combination required. Some examples:
+
+.. includecode2:: /../spray-routing-tests/src/test/scala/spray/routing/EncodingDirectivesSpec.scala
+   :snippet: decompress-compress-combination-example

akka-docs-dev/rst/scala/http/directives/coding-directives/requestEncodedWith.rst

@@ -0,0 +1,18 @@
+.. _-requestEncodedWith-:
+
+requestEncodedWith
+==================
+
+Passes the request to the inner route if the request is encoded with the argument encoding. Otherwise,
+rejects the request with an ``UnacceptedRequestEncodingRejection(encoding)``.
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: requestEncodedWith
+
+Description
+-----------
+
+This directive is the building block for ``decodeRequest`` to reject unsupported encodings.

akka-docs-dev/rst/scala/http/directives/coding-directives/responseEncodingAccepted.rst

@@ -0,0 +1,18 @@
+.. _-responseEncodingAccepted-:
+
+responseEncodingAccepted
+========================
+
+Passes the request to the inner route if the request accepts the argument encoding. Otherwise,
+rejects the request with an ``UnacceptedResponseEncodingRejection(encoding)``.
+
+Signature
+---------
+
+.. includecode2:: /../../akka-http/src/main/scala/akka/http/server/directives/CodingDirectives.scala
+   :snippet: responseEncodingAccepted
+
+Description
+-----------
+
+This directive is the building block for ``encodeResponse`` to reject unsupported encodings.