+doc,htp #18496 file directives docs
This commit is contained in:
Konrad Malawski
parent
4c81e6cbea
commit
2927568225
10 changed files with 155 additions and 64 deletions
|
|
@ -4,27 +4,14 @@
|
|||
|
||||
package docs.http.scaladsl.server.directives
|
||||
|
||||
import java.io.File
|
||||
|
||||
import akka.event.Logging
|
||||
import akka.http.scaladsl.marshalling.ToEntityMarshaller
|
||||
import akka.http.scaladsl.model._
|
||||
import akka.http.scaladsl.model.headers.RawHeader
|
||||
import akka.http.scaladsl.server.RouteResult.Rejected
|
||||
import akka.http.scaladsl.server._
|
||||
import akka.http.scaladsl.model.StatusCodes
|
||||
import akka.http.scaladsl.server.directives.DirectoryListing
|
||||
import akka.http.scaladsl.server.directives.FileAndResourceDirectives.DirectoryRenderer
|
||||
import akka.stream.ActorMaterializer
|
||||
import akka.stream.io.SynchronousFileSource
|
||||
import akka.stream.scaladsl.{ Sink, Source }
|
||||
import akka.util.ByteString
|
||||
import docs.http.scaladsl.server.RoutingSpec
|
||||
|
||||
import scala.concurrent.Future
|
||||
import scala.util.control.NonFatal
|
||||
|
||||
class FileAndResourceDirectivesExamplesSpec extends RoutingSpec {
|
||||
"0getFromFile" in compileOnlySpec {
|
||||
"getFromFile-examples" in compileOnlySpec {
|
||||
import akka.http.scaladsl.server.directives._
|
||||
import ContentTypeResolver.Default
|
||||
|
||||
|
|
@ -34,10 +21,10 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec {
|
|||
}
|
||||
|
||||
Get("/logs/example") ~> route ~> check {
|
||||
responseAs[String] shouldEqual "The length of the request URI is 25"
|
||||
responseAs[String] shouldEqual "example file contents"
|
||||
}
|
||||
}
|
||||
"0getFromResource" in compileOnlySpec {
|
||||
"getFromResource-examples" in compileOnlySpec {
|
||||
import akka.http.scaladsl.server.directives._
|
||||
import ContentTypeResolver.Default
|
||||
|
||||
|
|
@ -47,10 +34,10 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec {
|
|||
}
|
||||
|
||||
Get("/logs/example") ~> route ~> check {
|
||||
responseAs[String] shouldEqual "The length of the request URI is 25"
|
||||
responseAs[String] shouldEqual "example file contents"
|
||||
}
|
||||
}
|
||||
"0listDirectoryContents" in compileOnlySpec {
|
||||
"listDirectoryContents-examples" in compileOnlySpec {
|
||||
val route =
|
||||
path("tmp") {
|
||||
listDirectoryContents("/tmp")
|
||||
|
|
@ -63,7 +50,48 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec {
|
|||
}
|
||||
|
||||
Get("/logs/example") ~> route ~> check {
|
||||
responseAs[String] shouldEqual "The length of the request URI is 25"
|
||||
responseAs[String] shouldEqual "example file contents"
|
||||
}
|
||||
}
|
||||
"getFromBrowseableDirectory-examples" in compileOnlySpec {
|
||||
val route =
|
||||
path("tmp") {
|
||||
getFromBrowseableDirectory("/tmp")
|
||||
}
|
||||
|
||||
Get("/tmp") ~> route ~> check {
|
||||
status shouldEqual StatusCodes.OK
|
||||
}
|
||||
}
|
||||
"getFromBrowseableDirectories-examples" in compileOnlySpec {
|
||||
val route =
|
||||
path("tmp") {
|
||||
getFromBrowseableDirectories("/main", "/backups")
|
||||
}
|
||||
|
||||
|
||||
Get("/tmp") ~> route ~> check {
|
||||
status shouldEqual StatusCodes.OK
|
||||
}
|
||||
}
|
||||
"getFromDirectory-examples" in compileOnlySpec {
|
||||
val route =
|
||||
path("tmp") {
|
||||
getFromDirectory("/tmp")
|
||||
}
|
||||
|
||||
Get("/tmp/example") ~> route ~> check {
|
||||
responseAs[String] shouldEqual "example file contents"
|
||||
}
|
||||
}
|
||||
"getFromResourceDirectory-examples" in compileOnlySpec {
|
||||
val route =
|
||||
path("examples") {
|
||||
getFromResourceDirectory("/examples")
|
||||
}
|
||||
|
||||
Get("/examples/example-1") ~> route ~> check {
|
||||
responseAs[String] shouldEqual "example file contents"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
getFromBrowseableDirectories
|
||||
============================
|
||||
|
||||
Serves the content of the given directories as a file system browser, i.e. files are sent and directories
|
||||
served as browsable listings.
|
||||
Serves the content of the given directories as a file system browser,
|
||||
i.e. files are sent and directories served as *browsable* listings.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -15,9 +15,19 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories (like
|
||||
``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``. Nesting this directive beneath
|
||||
``get`` is not necessary as this directive will only respond to ``GET`` requests.
|
||||
The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories
|
||||
(like ``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``.
|
||||
|
||||
Use ``getFromBrowseableDirectory`` to serve only one directory. Use ``getFromDirectory`` if directory browsing isn't
|
||||
required.
|
||||
Nesting this directive beneath ``get`` is not necessary as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Use ``getFromBrowseableDirectory`` to serve only one directory.
|
||||
|
||||
Use ``getFromDirectory`` if directory browsing isn't required.
|
||||
|
||||
For more details refer to :ref:`-getFromBrowseableDirectory-`.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: getFromBrowseableDirectories-examples
|
||||
|
|
|
|||
|
|
@ -3,7 +3,8 @@
|
|||
getFromBrowseableDirectory
|
||||
==========================
|
||||
|
||||
The single-directory variant of :ref:`-getFromBrowseableDirectories-`.
|
||||
Serves the content of the given directory as a file system browser,
|
||||
i.e. files are sent and directories served as *browsable* listings.
|
||||
|
||||
Signature
|
||||
---------
|
||||
|
|
@ -14,8 +15,40 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories (like
|
||||
``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``.
|
||||
|
||||
Nesting this directive beneath ``get`` is not necessary as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Use ``getFromBrowseableDirectory`` to serve only one directory.
|
||||
|
||||
Use ``getFromDirectory`` if directory browsing isn't required.
|
||||
|
||||
For more details refer to :ref:`-getFromBrowseableDirectory-`.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
|
||||
:snippet: 0extractSettings
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: getFromBrowseableDirectory-examples
|
||||
|
||||
|
||||
Default file listing page example
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Directives which list directories (e.g. ``getFromBrowsableDirectory``) use an implicit ``DirectoryRenderer``
|
||||
instance to perfm the actual rendering of the file listing. This rendered can be easily overriden by simply
|
||||
providing one in-scope for the directives to use, so you can build your custom directory listings.
|
||||
|
||||
|
||||
The default renderer is ``akka.http.scaladsl.server.directives.FileAndResourceDirectives.defaultDirectoryRenderer``,
|
||||
and renders a listing which looks like this:
|
||||
|
||||
.. figure:: ../../../../../images/akka-http-file-listing.png
|
||||
:scale: 75%
|
||||
:align: center
|
||||
|
||||
Example page rendered by the ``defaultDirectoryRenderer``.
|
||||
|
||||
It's possible to turn off rendering the footer stating which version of Akka HTTP is rendering this page by configuring
|
||||
the ``akka.http.routing.render-vanity-footer`` configuration option to ``off``.
|
||||
|
|
@ -14,18 +14,27 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The ``unmatchedPath`` of the ``RequestContext`` is first transformed by the given ``pathRewriter`` function before being
|
||||
appended to the given directory name to build the final file name.
|
||||
Allows exposing a directory's files for GET requests for its contents.
|
||||
|
||||
The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread. If the file cannot
|
||||
be read the route rejects the request.
|
||||
The ``unmatchedPath`` (see :ref:`-extractUnmatchedPath-`) of the ``RequestContext`` is first transformed by
|
||||
the given ``pathRewriter`` function, before being appended to the given directory name to build the final file name.
|
||||
|
||||
To serve a single file use ``getFromFile``. To serve browsable directory listings use ``getFromBrowseableDirectories``.
|
||||
To serve files from a classpath directory use ``getFromResourceDirectory`` instead.
|
||||
To serve a single file use :ref:`-getFromFile-`.
|
||||
To serve browsable directory listings use :ref:`-getFromBrowseableDirectories-`.
|
||||
To serve files from a classpath directory use :ref:`-getFromResourceDirectory-` instead.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
.. note::
|
||||
The file's contents will be read using an Akka Streams :class:`SynchronousFileSource` which *automatically uses
|
||||
a pre-configured dedicated blocking io dispatcher*, which separates the blocking file operations from the rest of the stream.
|
||||
|
||||
Note also that thanks to using Akka Streams internally, the file will be served at the highest spead reachable by
|
||||
the client, and not faster – i.e. the file will *not* end up being loaded in full into memory before writing it to
|
||||
the client.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: getFromDirectory-examples
|
||||
|
|
@ -14,15 +14,27 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread (but potentially
|
||||
some other thread !). If the file cannot be found or read the request is rejected.
|
||||
Allows exposing a file to be streamed to the client issuing the request.
|
||||
|
||||
To serve files from a directory use ``getFromDirectory``, instead. To serve a file from a classpath resource
|
||||
use ``getFromResource`` instead.
|
||||
The ``unmatchedPath`` (see :ref:`-extractUnmatchedPath-`) of the ``RequestContext`` is first transformed by
|
||||
the given ``pathRewriter`` function, before being appended to the given directory name to build the final file name.
|
||||
|
||||
To files from a given directory use :ref:`-getFromDirectory-`.
|
||||
To serve browsable directory listings use :ref:`-getFromBrowseableDirectories-`.
|
||||
To serve files from a classpath directory use :ref:`-getFromResourceDirectory-` instead.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
.. note::
|
||||
The file's contents will be read using an Akka Streams :class:`SynchronousFileSource` which *automatically uses
|
||||
a pre-configured dedicated blocking io dispatcher*, which separates the blocking file operations from the rest of the stream.
|
||||
|
||||
Note also that thanks to using Akka Streams internally, the file will be served at the highest spead reachable by
|
||||
the client, and not faster – i.e. the file will *not* end up being loaded in full into memory before writing it to
|
||||
the client.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: getFromFile-examples
|
||||
|
|
|
|||
|
|
@ -14,15 +14,15 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The actual I/O operation is running detached in a ``Future``, so it doesn't block the current thread (but potentially
|
||||
some other thread !). If the file cannot be found or read the request is rejected.
|
||||
Completes GET requests with the content of the given classpath resource.
|
||||
|
||||
To serve files from a classpath directory use ``getFromResourceDirectory`` instead. To serve files from a filesystem
|
||||
directory use ``getFromDirectory``, instead.
|
||||
For details refer to :ref:`getFromFile` which works the same way but obtaining the file from the filesystem
|
||||
instead of the applications classpath.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: getFromResource-examples
|
||||
|
|
@ -14,15 +14,15 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread (but potentially
|
||||
some other thread !). If the file cannot be found or read the request is rejected.
|
||||
Completes GET requests with the content of the given classpath resource directory.
|
||||
|
||||
To serve a single resource use ``getFromResource``, instead. To server files from a filesystem directory use
|
||||
``getFromDirectory`` instead.
|
||||
For details refer to :ref:`getFromDirectory` which works the same way but obtaining the file from the filesystem
|
||||
instead of the applications classpath.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: getFromResourceDirectory-examples
|
||||
|
|
|
|||
|
|
@ -15,15 +15,19 @@ Signature
|
|||
Description
|
||||
-----------
|
||||
|
||||
The ``listDirectoryContents`` directive renders a response only for directories. To just serve files use
|
||||
``getFromDirectory``. To serve files and provide a browseable directory listing use ``getFromBrowsableDirectories``
|
||||
instead.
|
||||
The ``listDirectoryContents`` directive renders a response only for directories.
|
||||
|
||||
The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``.
|
||||
To just serve files use :ref:`-getFromDirectory-`.
|
||||
|
||||
To serve files and provide a browseable directory listing use :ref:`-getFromBrowsableDirectories-` instead.
|
||||
|
||||
The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``, you can read more about it in
|
||||
:ref:`-getFromDirectory-` 's documentation.
|
||||
|
||||
Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
...
|
||||
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala
|
||||
:snippet: listDirectoryContents-examples
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue