diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst index b96d3f5bcd..72c386b8f6 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst @@ -6,133 +6,194 @@ Predefined Directives (alphabetically) =========================================== ============================================================================ Directive Description =========================================== ============================================================================ -:ref:`-authenticateBasic-` ... -:ref:`-authenticateBasicAsync-` ... -:ref:`-authenticateBasicPF-` ... -:ref:`-authenticateBasicPFAsync-` ... -:ref:`-authenticateOrRejectWithChallenge-` ... -:ref:`-authorize-` ... -:ref:`-cancelRejection-` ... -:ref:`-cancelRejections-` ... -:ref:`-complete-` ... -:ref:`-completeOrRecoverWith-` ... -:ref:`-completeWith-` ... -:ref:`-conditional-` ... -:ref:`-cookie-` ... -:ref:`-decodeRequest-` ... -:ref:`-decodeRequestWith-` ... -:ref:`-delete-` ... -:ref:`-deleteCookie-` ... -:ref:`-encodeResponse-` ... -:ref:`-encodeResponseWith-` ... -:ref:`-entity-` ... -:ref:`-extract-` ... -:ref:`-extractClientIP-` ... -:ref:`-extractCredentials-` ... -:ref:`-extractExecutionContext-` ... -:ref:`-extractFlowMaterializer-` ... -:ref:`-extractHost-` ... -:ref:`-extractLog-` ... -:ref:`-extractMethod-` ... -:ref:`-extractRequest-` ... -:ref:`-extractRequestContext-` ... -:ref:`-extractScheme-` ... -:ref:`-extractSettings-` ... -:ref:`-extractUnmatchedPath-` ... -:ref:`-extractUri-` ... -:ref:`-failWith-` ... -:ref:`-formField-` ... -:ref:`-formFields-` ... -:ref:`-get-` ... -:ref:`-getFromBrowseableDirectories-` ... -:ref:`-getFromBrowseableDirectory-` ... -:ref:`-getFromDirectory-` ... -:ref:`-getFromFile-` ... -:ref:`-getFromResource-` ... -:ref:`-getFromResourceDirectory-` ... -:ref:`-handleExceptions-` ... -:ref:`-handleRejections-` ... -:ref:`-handleWebsocketMessages-` ... -:ref:`-handleWith-` ... -:ref:`-head-` ... -:ref:`-headerValue-` ... -:ref:`-headerValueByName-` ... -:ref:`-headerValueByType-` ... -:ref:`-headerValuePF-` ... -:ref:`-host-` ... -:ref:`-listDirectoryContents-` ... -:ref:`-logRequest-` ... -:ref:`-logRequestResult-` ... -:ref:`-logResult-` ... -:ref:`-mapInnerRoute-` ... -:ref:`-mapRejections-` ... -:ref:`-mapRequest-` ... -:ref:`-mapRequestContext-` ... -:ref:`-mapResponse-` ... -:ref:`-mapResponseEntity-` ... -:ref:`-mapResponseHeaders-` ... -:ref:`-mapRouteResult-` ... -:ref:`-mapRouteResultFuture-` ... -:ref:`-mapRouteResultPF-` ... -:ref:`-mapRouteResultWith-` ... -:ref:`-mapRouteResultWithPF-` ... -:ref:`-mapSettings-` ... -:ref:`-mapUnmatchedPath-` ... -:ref:`-method-` ... -:ref:`-onComplete-` ... -:ref:`-onSuccess-` ... -:ref:`-optionalCookie-` ... -:ref:`-optionalHeaderValue-` ... -:ref:`-optionalHeaderValueByName-` ... -:ref:`-optionalHeaderValueByType-` ... -:ref:`-optionalHeaderValuePF-` ... -:ref:`-options-` ... -:ref:`-overrideMethodWithParameter-` ... -:ref:`-overrideStatusCode-` ... -:ref:`-parameter-` ... -:ref:`-parameterMap-` ... -:ref:`-parameterMultiMap-` ... -:ref:`-parameters-` ... -:ref:`-parameterSeq-` ... -:ref:`-pass-` ... -:ref:`-patch-` ... -:ref:`-path-` ... -:ref:`-pathEnd-` ... -:ref:`-pathEndOrSingleSlash-` ... -:ref:`-pathPrefix-` ... -:ref:`-pathPrefixTest-` ... -:ref:`-pathSingleSlash-` ... -:ref:`-pathSuffix-` ... -:ref:`-pathSuffixTest-` ... -:ref:`-post-` ... -:ref:`-provide-` ... -:ref:`-put-` ... -:ref:`-rawPathPrefix-` ... -:ref:`-rawPathPrefixTest-` ... -:ref:`-recoverRejections-` ... -:ref:`-recoverRejectionsWith-` ... -:ref:`-redirect-` ... -:ref:`-redirectToNoTrailingSlashIfPresent-` ... -:ref:`-redirectToTrailingSlashIfMissing-` ... -:ref:`-reject-` ... -:ref:`-rejectEmptyResponse-` ... -:ref:`-requestEncodedWith-` ... -:ref:`-requestEntityEmpty-` ... -:ref:`-requestEntityPresent-` ... -:ref:`-respondWithDefaultHeader-` ... -:ref:`-respondWithDefaultHeaders-` ... -:ref:`-respondWithHeader-` ... -:ref:`-respondWithHeaders-` ... -:ref:`-respondWithHeaders-` ... -:ref:`-responseEncodingAccepted-` ... -:ref:`-scheme-` ... -:ref:`-setCookie-` ... -:ref:`-textract-` ... -:ref:`-tprovide-` ... -:ref:`-validate-` ... -:ref:`-withExecutionContext-` ... -:ref:`-withFlowMaterializer-` ... -:ref:`-withLog-` ... -:ref:`-withRangeSupport-` ... -:ref:`-withSettings-` ... +:ref:`-authenticateBasic-` Wraps the inner route with Http Basic authentication support using a given + ``Authenticator[T]`` +:ref:`-authenticateBasicAsync-` Wraps the inner route with Http Basic authentication support using a given + ``AsyncAuthenticator[T]`` +:ref:`-authenticateBasicPF-` Wraps the inner route with Http Basic authentication support using a given + ``AuthenticatorPF[T]`` +:ref:`-authenticateBasicPFAsync-` Wraps the inner route with Http Basic authentication support using a given + ``AsyncAuthenticatorPF[T]`` +:ref:`-authenticateOrRejectWithChallenge-` Lifts an authenticator function into a directive +:ref:`-authorize-` Applies the given authorization check to the request +:ref:`-cancelRejection-` Adds a ``TransformationRejection`` cancelling all rejections equal to the + given one to the rejections potentially coming back from the inner route. +:ref:`-cancelRejections-` Adds a ``TransformationRejection`` cancelling all matching rejections + to the rejections potentially coming back from the inner route +:ref:`-complete-` Completes the request using the given arguments +:ref:`-completeOrRecoverWith-` "Unwraps" a ``Future[T]`` and runs the inner route when the future has + failed with the error as an extraction of type ``Throwable`` +:ref:`-completeWith-` Uses the marshaller for a given type to extract a completion function +:ref:`-conditional-` Wraps its inner route with support for conditional requests as defined + by http://tools.ietf.org/html/rfc7232 +:ref:`-cookie-` Extracts the ``HttpCookie`` with the given name +:ref:`-decodeRequest-` Decompresses the request if it is ``gzip`` or ``deflate`` compressed +:ref:`-decodeRequestWith-` Decodes the incoming request using one of the given decoders +:ref:`-delete-` Rejects all non-DELETE requests +:ref:`-deleteCookie-` Adds a ``Set-Cookie`` response header expiring the given cookies +:ref:`-encodeResponse-` Encodes the response with the encoding that is requested by the client + via the ``Accept-Encoding`` header (``NoCoding``, ``Gzip`` and ``Deflate``) +:ref:`-encodeResponseWith-` Encodes the response with the encoding that is requested by the client + via the ``Accept-Encoding`` header (from a user-defined set) +:ref:`-entity-` Extracts the request entity unmarshalled to a given type +:ref:`-extract-` Extracts a single value using a ``RequestContext ⇒ T`` function +:ref:`-extractClientIP-` Extracts the client's IP from either the ``X-Forwarded-``, + ``Remote-Address`` or ``X-Real-IP`` header +:ref:`-extractCredentials-` Extracts the potentially present ``HttpCredentials`` provided with the + request's ``Authorization`` header +:ref:`-extractExecutionContext-` Extracts the ``ExecutionContext`` from the ``RequestContext`` +:ref:`-extractFlowMaterializer-` Extracts the ``FlowMaterializer`` from the ``RequestContext`` +:ref:`-extractHost-` Extracts the hostname part of the Host request header value +:ref:`-extractLog-` Extracts the ``LoggingAdapter`` from the ``RequestContext`` +:ref:`-extractMethod-` Extracts the request method +:ref:`-extractRequest-` Extracts the current ``HttpRequest`` instance +:ref:`-extractRequestContext-` Extracts the ``RequestContext`` itself +:ref:`-extractScheme-` Extracts the URI scheme from the request +:ref:`-extractSettings-` Extracts the ``RoutingSettings`` from the ``RequestContext`` +:ref:`-extractUnmatchedPath-` Extracts the yet unmatched path from the ``RequestContext`` +:ref:`-extractUri-` Extracts the complete request URI +:ref:`-failWith-` Bubbles the given error up the response chain where it is dealt with by the + closest :ref:`-handleExceptions-` directive and its ``ExceptionHandler`` +:ref:`-formField-` Extracts an HTTP form field from the request +:ref:`-formFields-` Extracts a number of HTTP form field from the request +:ref:`-get-` Rejects all non-GET requests +:ref:`-getFromBrowseableDirectories-` Serves the content of the given directories as a file-system browser, i.e. + files are sent and directories served as browseable listings +:ref:`-getFromBrowseableDirectory-` Serves the content of the given directory as a file-system browser, i.e. + files are sent and directories served as browseable listings +:ref:`-getFromDirectory-` Completes GET requests with the content of a file underneath a given + file-system directory +:ref:`-getFromFile-` Completes GET requests with the content of a given file +:ref:`-getFromResource-` Completes GET requests with the content of a given class-path resource +:ref:`-getFromResourceDirectory-` Completes GET requests with the content of a file underneath a given + "class-path resource directory" +:ref:`-handleExceptions-` Transforms exceptions thrown during evaluation of the inner route using the + given ``ExceptionHandler`` +:ref:`-handleRejections-` Transforms rejections produced by the inner route using the given + ``RejectionHandler`` +:ref:`-handleWebsocketMessages-` Handles websocket requests with the given handler and rejects other requests + with a ``ExpectedWebsocketRequestRejection`` +:ref:`-handleWith-` Completes the request using a given function +:ref:`-head-` Rejects all non-HEAD requests +:ref:`-headerValue-` Extracts an HTTP header value using a given ``HttpHeader ⇒ Option[T]`` + function +:ref:`-headerValueByName-` Extracts the value of the first HTTP request header with a given name +:ref:`-headerValueByType-` Extracts the first HTTP request header of the given type +:ref:`-headerValuePF-` Extracts an HTTP header value using a given + ``PartialFunction[HttpHeader, T]`` +:ref:`-host-` Rejects all requests with a non-matching host name +:ref:`-listDirectoryContents-` Completes GET requests with a unified listing of the contents of all given + file-system directories +:ref:`-logRequest-` Produces a log entry for every incoming request +:ref:`-logRequestResult-` Produces a log entry for every incoming request and ``RouteResult`` +:ref:`-logResult-` Produces a log entry for every ``RouteResult`` +:ref:`-mapInnerRoute-` Transforms its inner ``Route`` with a ``Route => Route`` function +:ref:`-mapRejections-` Transforms rejections from a previous route with an + ``immutable.Seq[Rejection] ⇒ immutable.Seq[Rejection]`` function +:ref:`-mapRequest-` Transforms the request with an ``HttpRequest => HttpRequest`` function +:ref:`-mapRequestContext-` Transforms the ``RequestContext`` with a + ``RequestContext => RequestContext`` function +:ref:`-mapResponse-` Transforms the response with an ``HttpResponse => HttpResponse`` function +:ref:`-mapResponseEntity-` Transforms the response entity with an ``ResponseEntity ⇒ ResponseEntity`` + function +:ref:`-mapResponseHeaders-` Transforms the response headers with an + ``immutable.Seq[HttpHeader] ⇒ immutable.Seq[HttpHeader]`` function +:ref:`-mapRouteResult-` Transforms the ``RouteResult`` with a ``RouteResult ⇒ RouteResult`` + function +:ref:`-mapRouteResultFuture-` Transforms the ``RouteResult`` future with a + ``Future[RouteResult] ⇒ Future[RouteResult]`` function +:ref:`-mapRouteResultPF-` Transforms the ``RouteResult`` with a + ``PartialFunction[RouteResult, RouteResult]`` +:ref:`-mapRouteResultWith-` Transforms the ``RouteResult`` with a + ``RouteResult ⇒ Future[RouteResult]`` function +:ref:`-mapRouteResultWithPF-` Transforms the ``RouteResult`` with a + ``PartialFunction[RouteResult, Future[RouteResult]]`` +:ref:`-mapSettings-` Transforms the ``RoutingSettings`` with a + ``RoutingSettings ⇒ RoutingSettings`` function +:ref:`-mapUnmatchedPath-` Transforms the ``unmatchedPath`` of the ``RequestContext`` using a + ``Uri.Path ⇒ Uri.Path`` function +:ref:`-method-` Rejects all requests whose HTTP method does not match the given one +:ref:`-onComplete-` "Unwraps" a ``Future[T]`` and runs the inner route after future completion + with the future's value as an extraction of type ``Try[T]`` +:ref:`-onSuccess-` "Unwraps" a ``Future[T]`` and runs the inner route after future completion + with the future's value as an extraction of type ``T`` +:ref:`-optionalCookie-` Extracts the ``HttpCookiePair`` with the given name as an + ``Option[HttpCookiePair]`` +:ref:`-optionalHeaderValue-` Extracts an optional HTTP header value using a given + ``HttpHeader ⇒ Option[T]`` function +:ref:`-optionalHeaderValueByName-` Extracts the value of the first optional HTTP request header with a given + name +:ref:`-optionalHeaderValueByType-` Extracts the first optional HTTP request header of the given type +:ref:`-optionalHeaderValuePF-` Extracts an optional HTTP header value using a given + ``PartialFunction[HttpHeader, T]`` +:ref:`-options-` Rejects all non-OPTIONS requests +:ref:`-overrideMethodWithParameter-` Changes the request method to the value of the specified query parameter +:ref:`-overrideStatusCode-` Overrides the response status code with the given one +:ref:`-parameter-` Extracts a query parameter value from the request +:ref:`-parameterMap-` Extracts the request's query parameters as a ``Map[String, String]`` +:ref:`-parameterMultiMap-` Extracts the request's query parameters as a ``Map[String, List[String]]`` +:ref:`-parameters-` Extracts a number of query parameter values from the request +:ref:`-parameterSeq-` Extracts the request's query parameters as a ``Seq[(String, String)]`` +:ref:`-pass-` Always simply passes the request on to its inner route, i.e. doesn't do + anything, neither with the request nor the response +:ref:`-patch-` Rejects all non-PATCH requests +:ref:`-path-` Applies the given ``PathMatcher`` to the remaining unmatched path after + consuming a leading slash +:ref:`-pathEnd-` Only passes on the request to its inner route if the request path has been + matched completely +:ref:`-pathEndOrSingleSlash-` Only passes on the request to its inner route if the request path has been + matched completely or only consists of exactly one remaining slash +:ref:`-pathPrefix-` Applies the given ``PathMatcher`` to a prefix of the remaining unmatched + path after consuming a leading slash +:ref:`-pathPrefixTest-` Checks whether the unmatchedPath has a prefix matched by the given + ``PathMatcher`` after implicitly consuming a leading slash +:ref:`-pathSingleSlash-` Only passes on the request to its inner route if the request path + consists of exactly one remaining slash +:ref:`-pathSuffix-` Applies the given ``PathMatcher`` to a suffix of the remaining unmatched + path (Caution: check scaladoc!) +:ref:`-pathSuffixTest-` Checks whether the unmatched path has a suffix matched by the given + ``PathMatcher`` (Caution: check scaladoc!) +:ref:`-post-` Rejects all non-POST requests +:ref:`-provide-` Injects a given value into a directive +:ref:`-put-` Rejects all non-PUT requests +:ref:`-rawPathPrefix-` Applies the given matcher directly to a prefix of the unmatched path of the + ``RequestContext``, without implicitly consuming a leading slash +:ref:`-rawPathPrefixTest-` Checks whether the unmatchedPath has a prefix matched by the given + ``PathMatcher`` +:ref:`-recoverRejections-` Transforms rejections from a previous route with an + ``immutable.Seq[Rejection] ⇒ RouteResult`` function +:ref:`-recoverRejectionsWith-` Transforms rejections from a previous route with an + ``immutable.Seq[Rejection] ⇒ Future[RouteResult]`` function +:ref:`-redirect-` Completes the request with redirection response of the given type to the + given URI +:ref:`-redirectToNoTrailingSlashIfPresent-` If the request path ends with a slash, redirects to the same uri without + trailing slash in the path +:ref:`-redirectToTrailingSlashIfMissing-` If the request path doesn't end with a slash, redirects to the same uri with + trailing slash in the path +:ref:`-reject-` Rejects the request with the given rejections +:ref:`-rejectEmptyResponse-` Converts responses with an empty entity into (empty) rejections +:ref:`-requestEncodedWith-` Rejects the request with an ``UnsupportedRequestEncodingRejection`` if its + encoding doesn't match the given one +:ref:`-requestEntityEmpty-` Rejects if the request entity is non-empty +:ref:`-requestEntityPresent-` Rejects with a ``RequestEntityExpectedRejection`` if the request entity is + empty +:ref:`-respondWithDefaultHeader-` Adds a given response header if the response doesn't already contain a + header with the same name +:ref:`-respondWithDefaultHeaders-` Adds the subset of the given headers to the response which doesn't already + have a header with the respective name present in the response +:ref:`-respondWithHeader-` Unconditionally adds a given header to the outgoing response +:ref:`-respondWithHeaders-` Unconditionally adds the given headers to the outgoing response +:ref:`-responseEncodingAccepted-` Rejects the request with an ``UnacceptedResponseEncodingRejection`` if the + given response encoding is not accepted by the client +:ref:`-scheme-` Rejects all requests whose URI scheme doesn't match the given one +:ref:`-setCookie-` Adds a ``Set-Cookie`` response header with the given cookies +:ref:`-textract-` Extracts a number of values using a ``RequestContext ⇒ Tuple`` function +:ref:`-tprovide-` Injects a given tuple of values into a directive +:ref:`-validate-` Checks a given condition before running its inner route +:ref:`-withExecutionContext-` Runs its inner route with the given alternative ``ExecutionContext`` +:ref:`-withFlowMaterializer-` Runs its inner route with the given alternative ``FlowMaterializer`` +:ref:`-withLog-` Runs its inner route with the given alternative ``LoggingAdapter`` +:ref:`-withRangeSupport-` Adds ``Accept-Ranges: bytes`` to responses to GET requests, produces partial + responses if the initial request contained a valid ``Range`` header +:ref:`-withSettings-` Runs its inner route with the given alternative ``RoutingSettings`` =========================================== ============================================================================ diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/BasicDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/BasicDirectives.scala index ec8c58597b..27d3aa1f2b 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/BasicDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/BasicDirectives.scala @@ -115,12 +115,12 @@ trait BasicDirectives { mapRequestContext(_ mapUnmatchedPath f) /** - * Extracts the unmatched path from the RequestContext. + * Extracts the yet unmatched path from the RequestContext. */ def extractUnmatchedPath: Directive1[Uri.Path] = BasicDirectives._extractUnmatchedPath /** - * Extracts the complete request. + * Extracts the current [[HttpRequest]] instance. */ def extractRequest: Directive1[HttpRequest] = BasicDirectives._extractRequest diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala index e7a937fc2e..5a5c46c9a5 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala @@ -23,14 +23,14 @@ trait CodingDirectives { /** * Rejects the request with an UnacceptedResponseEncodingRejection - * if the given encoding is not accepted for the response. + * if the given response encoding is not accepted by the client. */ def responseEncodingAccepted(encoding: HttpEncoding): Directive0 = extract(_.request.isEncodingAccepted(encoding)) .flatMap(if (_) pass else reject(UnacceptedResponseEncodingRejection(Set(encoding)))) /** - * Encodes the response with the encoding that is requested by the client with the `Accept- + * Encodes the response with the encoding that is requested by the client via the `Accept- * Encoding` header. The response encoding is determined by the rules specified in * http://tools.ietf.org/html/rfc7231#section-5.3.4. * @@ -41,7 +41,7 @@ trait CodingDirectives { encodeResponseWith(NoCoding, Gzip, Deflate) /** - * Encodes the response with the encoding that is requested by the client with the `Accept- + * Encodes the response with the encoding that is requested by the client via the `Accept- * Encoding` header. The response encoding is determined by the rules specified in * http://tools.ietf.org/html/rfc7231#section-5.3.4. * diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CookieDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CookieDirectives.scala index 2bcb530ed1..893a9976fb 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CookieDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/CookieDirectives.scala @@ -6,7 +6,7 @@ package akka.http.scaladsl.server package directives import akka.http.scaladsl.model._ -import headers._ +import akka.http.scaladsl.model.headers._ import akka.http.impl.util._ trait CookieDirectives { @@ -15,14 +15,14 @@ trait CookieDirectives { import RouteDirectives._ /** - * Extracts an HttpCookie with the given name. If the cookie is not present the + * Extracts the [[HttpCookiePair]] with the given name. If the cookie is not present the * request is rejected with a respective [[MissingCookieRejection]]. */ def cookie(name: String): Directive1[HttpCookiePair] = headerValue(findCookie(name)) | reject(MissingCookieRejection(name)) /** - * Extracts an HttpCookie with the given name. + * Extracts the [[HttpCookiePair]] with the given name as an ``Option[HttpCookiePair]``. * If the cookie is not present a value of `None` is extracted. */ def optionalCookie(name: String): Directive1[Option[HttpCookiePair]] = @@ -34,13 +34,13 @@ trait CookieDirectives { } /** - * Adds a Set-Cookie header with the given cookies to all responses of its inner route. + * Adds a [[Set-Cookie]] response header with the given cookies. */ def setCookie(first: HttpCookie, more: HttpCookie*): Directive0 = respondWithHeaders((first :: more.toList).map(`Set-Cookie`(_))) /** - * Adds a Set-Cookie header expiring the given cookies to all responses of its inner route. + * Adds a [[Set-Cookie]] response header expiring the given cookies. */ def deleteCookie(first: HttpCookie, more: HttpCookie*): Directive0 = respondWithHeaders((first :: more.toList).map { c ⇒ @@ -48,7 +48,7 @@ trait CookieDirectives { }) /** - * Adds a Set-Cookie header expiring the given cookie to all responses of its inner route. + * Adds a [[Set-Cookie]] response header expiring the cookie with the given properties. */ def deleteCookie(name: String, domain: String = "", path: String = ""): Directive0 = deleteCookie(HttpCookie(name, "", domain = domain.toOption, path = path.toOption)) diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/DebuggingDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/DebuggingDirectives.scala index a7fe5d6809..3652795f3c 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/DebuggingDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/DebuggingDirectives.scala @@ -12,12 +12,18 @@ import akka.http.scaladsl.model._ trait DebuggingDirectives { import BasicDirectives._ + /** + * Produces a log entry for every incoming request. + */ def logRequest(magnet: LoggingMagnet[HttpRequest ⇒ Unit]): Directive0 = extractRequestContext.flatMap { ctx ⇒ magnet.f(ctx.log)(ctx.request) pass } + /** + * Produces a log entry for every [[RouteResult]]. + */ def logResult(magnet: LoggingMagnet[RouteResult ⇒ Unit]): Directive0 = extractRequestContext.flatMap { ctx ⇒ mapRouteResult { result ⇒ @@ -26,6 +32,9 @@ trait DebuggingDirectives { } } + /** + * Produces a log entry for every incoming request and [[RouteResult]]. + */ def logRequestResult(magnet: LoggingMagnet[HttpRequest ⇒ RouteResult ⇒ Unit]): Directive0 = extractRequestContext.flatMap { ctx ⇒ val logResult = magnet.f(ctx.log)(ctx.request) diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FileAndResourceDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FileAndResourceDirectives.scala index cbe4efeae0..3405295164 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FileAndResourceDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FileAndResourceDirectives.scala @@ -26,25 +26,22 @@ trait FileAndResourceDirectives { import RangeDirectives._ /** - * Completes GET requests with the content of the given file. 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 file. + * If the file cannot be found or read the request is rejected. */ def getFromFile(fileName: String)(implicit resolver: ContentTypeResolver): Route = getFromFile(new File(fileName)) /** - * Completes GET requests with the content of the given file. 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 file. + * If the file cannot be found or read the request is rejected. */ def getFromFile(file: File)(implicit resolver: ContentTypeResolver): Route = getFromFile(file, resolver(file.getName)) /** - * Completes GET requests with the content of the given file. 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 file. + * If the file cannot be found or read the request is rejected. */ def getFromFile(file: File, contentType: ContentType): Route = get { @@ -71,18 +68,14 @@ trait FileAndResourceDirectives { } else pass) /** - * Completes GET requests with the content of the given resource. The actual I/O operation is - * running detached in a `Future`, so it doesn't block the current thread (but potentially - * some other thread !). + * Completes GET requests with the content of the given class-path resource. * If the resource cannot be found or read the Route rejects the request. */ def getFromResource(resourceName: String)(implicit resolver: ContentTypeResolver): Route = getFromResource(resourceName, resolver(resourceName)) /** - * Completes GET requests with the content of the given resource. The actual I/O operation is - * running detached in a `Future`, so it doesn't block the current thread (but potentially - * some other thread !). + * Completes GET requests with the content of the given resource. * If the resource is a directory or cannot be found or read the Route rejects the request. */ def getFromResource(resourceName: String, contentType: ContentType, classLoader: ClassLoader = defaultClassLoader): Route = diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FormFieldDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FormFieldDirectives.scala index 991366a874..174e39ecf2 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FormFieldDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FormFieldDirectives.scala @@ -16,14 +16,14 @@ trait FormFieldDirectives extends ToNameReceptacleEnhancements { import FormFieldDirectives._ /** + * Extracts an HTTP form field from the request. * Rejects the request if the defined form field matcher(s) don't match. - * Otherwise the form field value(s) are extracted and passed to the inner route. */ def formField(pdm: FieldMagnet): pdm.Out = pdm() /** + * Extracts a number of HTTP form field from the request. * Rejects the request if the defined form field matcher(s) don't match. - * Otherwise the form field value(s) are extracted and passed to the inner route. */ def formFields(pdm: FieldMagnet): pdm.Out = pdm() diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FutureDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FutureDirectives.scala index 5bd4b10569..d5084bfe00 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FutureDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/FutureDirectives.scala @@ -16,7 +16,7 @@ import akka.http.scaladsl.util.FastFuture._ trait FutureDirectives { /** - * "Unwraps" a ``Future[T]`` and runs its inner route after future + * "Unwraps" a ``Future[T]`` and runs the inner route after future * completion with the future's value as an extraction of type ``Try[T]``. */ def onComplete[T](future: ⇒ Future[T]): Directive1[Try[T]] = @@ -26,7 +26,7 @@ trait FutureDirectives { } /** - * "Unwraps" a ``Future[T]`` and runs its inner route after future + * "Unwraps" a ``Future[T]`` and runs the inner route after future * completion with the future's value as an extraction of type ``T``. * If the future fails its failure Throwable is bubbled up to the nearest * ExceptionHandler. @@ -36,7 +36,7 @@ trait FutureDirectives { def onSuccess(magnet: OnSuccessMagnet): Directive[magnet.Out] = magnet.directive /** - * "Unwraps" a ``Future[T]`` and runs its inner route when the future has failed + * "Unwraps" a ``Future[T]`` and runs the inner route when the future has failed * with the future's failure exception as an extraction of type ``Throwable``. * If the future succeeds the request is completed using the values marshaller * (This directive therefore requires a marshaller for the futures type to be diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HeaderDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HeaderDirectives.scala index 5c670dd4d3..42be1e0ebd 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HeaderDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HeaderDirectives.scala @@ -40,7 +40,7 @@ trait HeaderDirectives { def headerValuePF[T](pf: PartialFunction[HttpHeader, T]): Directive1[T] = headerValue(pf.lift) /** - * Extracts the value of the HTTP request header with the given name. + * Extracts the value of the first HTTP request header with the given name. * If no header with a matching name is found the request is rejected with a [[spray.routing.MissingHeaderRejection]]. */ def headerValueByName(headerName: Symbol): Directive1[String] = headerValueByName(headerName.toString) @@ -53,7 +53,7 @@ trait HeaderDirectives { headerValue(optionalValue(headerName.toLowerCase)) | reject(MissingHeaderRejection(headerName)) /** - * Extracts the HTTP request header of the given type. + * Extracts the first HTTP request header of the given type. * If no header with a matching type is found the request is rejected with a [[spray.routing.MissingHeaderRejection]]. */ def headerValueByType[T <: HttpHeader](magnet: ClassMagnet[T]): Directive1[T] = diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HostDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HostDirectives.scala index de52962b6d..977978ba74 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HostDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/HostDirectives.scala @@ -13,7 +13,7 @@ trait HostDirectives { import RouteDirectives._ /** - * Extracts the hostname part of the Host header value in the request. + * Extracts the hostname part of the Host request header value. */ def extractHost: Directive1[String] = HostDirectives._extractHost diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MethodDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MethodDirectives.scala index 08f6f98491..820cb0cd62 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MethodDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MethodDirectives.scala @@ -15,37 +15,37 @@ trait MethodDirectives { import MethodDirectives._ /** - * A route filter that rejects all non-DELETE requests. + * Rejects all non-DELETE requests. */ def delete: Directive0 = _delete /** - * A route filter that rejects all non-GET requests. + * Rejects all non-GET requests. */ def get: Directive0 = _get /** - * A route filter that rejects all non-HEAD requests. + * Rejects all non-HEAD requests. */ def head: Directive0 = _head /** - * A route filter that rejects all non-OPTIONS requests. + * Rejects all non-OPTIONS requests. */ def options: Directive0 = _options /** - * A route filter that rejects all non-PATCH requests. + * Rejects all non-PATCH requests. */ def patch: Directive0 = _patch /** - * A route filter that rejects all non-POST requests. + * Rejects all non-POST requests. */ def post: Directive0 = _post /** - * A route filter that rejects all non-PUT requests. + * Rejects all non-PUT requests. */ def put: Directive0 = _put diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala index 42d531e816..3262d34b08 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala @@ -12,33 +12,33 @@ trait MiscDirectives { import RouteDirectives._ /** - * Returns a Directive which checks the given condition before passing on the [[spray.routing.RequestContext]] to - * its inner Route. If the condition fails the route is rejected with a [[spray.routing.ValidationRejection]]. + * Checks the given condition before running its inner route. + * If the condition fails the route is rejected with a [[ValidationRejection]]. */ def validate(check: ⇒ Boolean, errorMsg: String): Directive0 = Directive { inner ⇒ if (check) inner() else reject(ValidationRejection(errorMsg)) } /** - * Directive extracting the IP of the client from either the X-Forwarded-For, Remote-Address or X-Real-IP header + * Extracts the client's IP from either the X-Forwarded-For, Remote-Address or X-Real-IP header * (in that order of priority). */ def extractClientIP: Directive1[RemoteAddress] = MiscDirectives._extractClientIP /** - * Rejects the request if its entity is not empty. + * Rejects if the request entity is non-empty. */ def requestEntityEmpty: Directive0 = MiscDirectives._requestEntityEmpty /** - * Rejects empty requests with a RequestEntityExpectedRejection. + * Rejects with a [[RequestEntityExpectedRejection]] if the request entity is empty. * Non-empty requests are passed on unchanged to the inner route. */ def requestEntityPresent: Directive0 = MiscDirectives._requestEntityPresent /** * Converts responses with an empty entity into (empty) rejections. - * This way you can, for example, have the marshalling of a ''None'' option be treated as if the request could - * not be matched. + * This way you can, for example, have the marshalling of a ''None'' option + * be treated as if the request could not be matched. */ def rejectEmptyResponse: Directive0 = MiscDirectives._rejectEmptyResponse } diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/ParameterDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/ParameterDirectives.scala index 90b0dfb6fb..1a7a63ce94 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/ParameterDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/ParameterDirectives.scala @@ -15,29 +15,29 @@ trait ParameterDirectives extends ToNameReceptacleEnhancements { import ParameterDirectives._ /** - * Extracts the requests query parameters as a Map[String, String]. + * Extracts the request's query parameters as a ``Map[String, String]``. */ def parameterMap: Directive1[Map[String, String]] = _parameterMap /** - * Extracts the requests query parameters as a Map[String, List[String]]. + * Extracts the request's query parameters as a ``Map[String, List[String]]``. */ def parameterMultiMap: Directive1[Map[String, List[String]]] = _parameterMultiMap /** - * Extracts the requests query parameters as a Seq[(String, String)]. + * Extracts the request's query parameters as a ``Seq[(String, String)]``. */ def parameterSeq: Directive1[immutable.Seq[(String, String)]] = _parameterSeq /** + * Extracts a query parameter value from the request. * Rejects the request if the defined query parameter matcher(s) don't match. - * Otherwise the parameter value(s) are extracted and passed to the inner route. */ def parameter(pdm: ParamMagnet): pdm.Out = pdm() /** + * Extracts a number of query parameter values from the request. * Rejects the request if the defined query parameter matcher(s) don't match. - * Otherwise the parameter value(s) are extracted and passed to the inner route. */ def parameters(pdm: ParamMagnet): pdm.Out = pdm() diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/PathDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/PathDirectives.scala index 3c2896056e..3ada67aecd 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/PathDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/PathDirectives.scala @@ -15,23 +15,22 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w import PathMatcher._ /** - * Consumes a leading slash from the unmatched path of the [[akka.http.scaladsl.server.RequestContext]] - * before applying the given matcher. The matcher has to match the remaining path completely - * or leave only a single trailing slash. - * If matched the value extracted by the PathMatcher is extracted on the directive level. + * Applies the given [[PathMatcher]] to the remaining unmatched path after consuming a leading slash. + * The matcher has to match the remaining path completely. + * If matched the value extracted by the [[PathMatcher]] is extracted on the directive level. */ def path[L](pm: PathMatcher[L]): Directive[L] = pathPrefix(pm ~ PathEnd) /** - * Consumes a leading slash from the unmatched path of the [[akka.http.scaladsl.server.RequestContext]] - * before applying the given matcher. The matcher has to match a prefix of the remaining path. + * Applies the given [[PathMatcher]] to a prefix of the remaining unmatched path after consuming a leading slash. + * The matcher has to match a prefix of the remaining path. * If matched the value extracted by the PathMatcher is extracted on the directive level. */ def pathPrefix[L](pm: PathMatcher[L]): Directive[L] = rawPathPrefix(Slash ~ pm) /** - * Applies the given matcher directly to the unmatched path of the [[akka.http.scaladsl.server.RequestContext]] - * (i.e. without implicitly consuming a leading slash). + * Applies the given matcher directly to a prefix of the unmatched path of the + * [[RequestContext]] (i.e. without implicitly consuming a leading slash). * The matcher has to match a prefix of the remaining path. * If matched the value extracted by the PathMatcher is extracted on the directive level. */ @@ -44,13 +43,13 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w } /** - * Checks whether the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] has a prefix matched by the + * Checks whether the unmatchedPath of the [[RequestContext]] has a prefix matched by the * given PathMatcher. In analogy to the `pathPrefix` directive a leading slash is implied. */ def pathPrefixTest[L](pm: PathMatcher[L]): Directive[L] = rawPathPrefixTest(Slash ~ pm) /** - * Checks whether the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] has a prefix matched by the + * Checks whether the unmatchedPath of the [[RequestContext]] has a prefix matched by the * given PathMatcher. However, as opposed to the `pathPrefix` directive the matched path is not * actually "consumed". */ @@ -63,10 +62,9 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w } /** - * Rejects the request if the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] does not have a suffix - * matched the given PathMatcher. If matched the value extracted by the PathMatcher is extracted - * and the matched parts of the path are consumed. - * Note that, for efficiency reasons, the given PathMatcher must match the desired suffix in reversed-segment + * Applies the given [[PathMatcher]] to a suffix of the remaining unmatchedPath of the [[RequestContext]]. + * If matched the value extracted by the [[PathMatcher]] is extracted and the matched parts of the path are consumed. + * Note that, for efficiency reasons, the given [[PathMatcher]] must match the desired suffix in reversed-segment * order, i.e. `pathSuffix("baz" / "bar")` would match `/foo/bar/baz`! */ def pathSuffix[L](pm: PathMatcher[L]): Directive[L] = { @@ -78,7 +76,7 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w } /** - * Checks whether the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] has a suffix matched by the + * Checks whether the unmatchedPath of the [[RequestContext]] has a suffix matched by the * given PathMatcher. However, as opposed to the pathSuffix directive the matched path is not * actually "consumed". * Note that, for efficiency reasons, the given PathMatcher must match the desired suffix in reversed-segment @@ -93,7 +91,7 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w } /** - * Rejects the request if the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] is non-empty, + * Rejects the request if the unmatchedPath of the [[RequestContext]] is non-empty, * or said differently: only passes on the request to its inner route if the request path * has been matched completely. */ diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/RespondWithDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/RespondWithDirectives.scala index 12557ad8fd..b9cf0050ab 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/RespondWithDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/RespondWithDirectives.scala @@ -8,7 +8,7 @@ trait RespondWithDirectives { import BasicDirectives._ /** - * Overrides the given response status on all HTTP responses of its inner Route. + * Overrides the response status code with the given one. */ def overrideStatusCode(responseStatus: StatusCode): Directive0 = mapResponse(_.copy(status = responseStatus)) diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala index a15fa095b8..ab3b625e66 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala @@ -41,7 +41,7 @@ trait SecurityDirectives { optionalHeaderValueByType[Authorization]().map(_.map(_.credentials)) /** - * A directive that wraps the inner route with Http Basic authentication support. + * Wraps the inner route with Http Basic authentication support using a given ``Authenticator[T]``. * The given authenticator determines whether the credentials in the request are valid * and, if so, which user object to supply to the inner route. */ @@ -49,7 +49,7 @@ trait SecurityDirectives { authenticateBasicAsync(realm, cred ⇒ FastFuture.successful(authenticator(cred))) /** - * A directive that wraps the inner route with Http Basic authentication support. + * Wraps the inner route with Http Basic authentication support. * The given authenticator determines whether the credentials in the request are valid * and, if so, which user object to supply to the inner route. */ diff --git a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/WebsocketDirectives.scala b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/WebsocketDirectives.scala index 7ea1bd6ab6..6117947b44 100644 --- a/akka-http/src/main/scala/akka/http/scaladsl/server/directives/WebsocketDirectives.scala +++ b/akka-http/src/main/scala/akka/http/scaladsl/server/directives/WebsocketDirectives.scala @@ -9,7 +9,6 @@ import akka.http.scaladsl.model.ws.{ UpgradeToWebsocket, Message } import akka.stream.scaladsl.Flow trait WebsocketDirectives { - import BasicDirectives._ import RouteDirectives._ import HeaderDirectives._