Make cask.QueryParams work for JSON endpoints, and form endpoints, …

…replace `subpath = true` with `cask.RemainingPathSegments` (#109)

`subpath = true` as a named argument passed to the annotation runs into
issues if multiple named arguments are present (see
https://stackoverflow.com/questions/55032173/how-to-use-named-arguments-in-scala-user-defined-annotations),
which prevents us from using named arguments to the annotation more
broadly as a user-facing API.

Using typed parameters to the method `def` sidesteps this issue, and
neatly allows us to provide the captured value to the user. This is also
more in line with how we handle inputs in general: cookies, known/typed
query params, unknown query params, json input, form fields, etc.

cask/src/cask/endpoints/JsonEndpoint.scala

@@ -24,6 +24,8 @@ object JsReader{
  implicit def paramReader[T: ParamReader]: JsReader[T] = new JsReader[T] {
  override def arity = 0
 
+ override def unknownQueryParams: Boolean = implicitly[ParamReader[T]].unknownQueryParams
+ override def remainingPathSegments: Boolean = implicitly[ParamReader[T]].remainingPathSegments
  override def read(ctx: cask.model.Request, label: String, v: ujson.Value) = {
  implicitly[ParamReader[T]].read(ctx, label, Nil)
  }

cask/src/cask/endpoints/ParamReader.scala

@@ -25,4 +25,24 @@ object ParamReader{
  implicit object CookieParam extends NilParam[Cookie]((ctx, label) =>
  Cookie.fromUndertow(ctx.exchange.getRequestCookies().get(label))
  )
+
+ implicit object QueryParams extends ParamReader[cask.model.QueryParams] {
+ def arity: Int = 0
+
+ override def unknownQueryParams = true
+
+ def read(ctx: cask.model.Request, label: String, v: Unit) = {
+ cask.model.QueryParams(ctx.queryParams)
+ }
+ }
+
+ implicit object RemainingPathSegments extends ParamReader[cask.model.RemainingPathSegments] {
+ def arity: Int = 0
+
+ override def remainingPathSegments = true
+
+ def read(ctx: cask.model.Request, label: String, v: Unit) = {
+ cask.model.RemainingPathSegments(ctx.remainingPathSegments)
+ }
+ }
 }

cask/src/cask/endpoints/WebEndpoints.scala

@@ -55,15 +55,8 @@ abstract class QueryParamReader[T]
  def read(ctx: cask.model.Request, label: String, v: Seq[String]): T
 }
 object QueryParamReader{
- implicit object QueryParams extends QueryParamReader[cask.model.QueryParams]{
- def arity: Int = 0
 
- override def unknownQueryParams = true
- def read(ctx: cask.model.Request, label: String, v: Seq[String]) = {
- cask.model.QueryParams(ctx.queryParams)
- }
 
- }
  class SimpleParam[T](f: String => T) extends QueryParamReader[T]{
  def arity = 1
  def read(ctx: cask.model.Request, label: String, v: Seq[String]): T = f(v.head)
@@ -92,6 +85,8 @@ object QueryParamReader{
  implicit def paramReader[T: ParamReader]: QueryParamReader[T] = new QueryParamReader[T] {
  override def arity = 0
 
+ override def unknownQueryParams: Boolean = implicitly[ParamReader[T]].unknownQueryParams
+ override def remainingPathSegments: Boolean = implicitly[ParamReader[T]].remainingPathSegments
  override def read(ctx: cask.model.Request, label: String, v: Seq[String]) = {
  implicitly[ParamReader[T]].read(ctx, label, v)
  }

cask/src/cask/main/Main.scala

@@ -150,7 +150,11 @@ object Main{
  val segments = Util.splitPath(metadata.endpoint.path)
  val methods = metadata.endpoint.methods.map(_ -> (routes, metadata: EndpointMetadata[_]))
  val methodMap = methods.toMap[String, (Routes, EndpointMetadata[_])]
- (segments, methodMap, metadata.endpoint.subpath)
+ val subpath =
+ metadata.endpoint.subpath ||
+ metadata.entryPoint.argSignatures.exists(_.exists(_.reads.remainingPathSegments))
+
+ (segments, methodMap, subpath)
  }
 
  val dispatchInputs = flattenedRoutes.groupBy(_._1).map { case (segments, values) =>

cask/src/cask/model/Params.scala

@@ -7,6 +7,7 @@ import io.undertow.server.HttpServerExchange
 import io.undertow.server.handlers.CookieImpl
 
 case class QueryParams(value: Map[String, collection.Seq[String]])
+case class RemainingPathSegments(value: Seq[String])
 
 case class Request(exchange: HttpServerExchange, remainingPathSegments: Seq[String])
 extends geny.ByteData with geny.Readable {

cask/src/cask/package.scala

@@ -20,6 +20,8 @@ package object cask {
  val Request = model.Request
  type QueryParams = model.QueryParams
  val QueryParams = model.QueryParams
+ type RemainingPathSegments = model.RemainingPathSegments
+ val RemainingPathSegments = model.RemainingPathSegments
 
  // endpoints
  type websocket = endpoints.websocket

cask/src/cask/router/Misc.scala

@@ -20,5 +20,6 @@ case class ArgSig[I, -T, +V, -C](name: String,
 trait ArgReader[I, +T, -C]{
  def arity: Int
  def unknownQueryParams: Boolean = false
+ def remainingPathSegments: Boolean = false
  def read(ctx: C, label: String, input: I): T
 }

docs/pages/1 - Cask: a Scala HTTP micro-framework.md

@@ -151,17 +151,13 @@ take
  least one value
 * `param: Seq[T] = Nil` for repeated params such as `?param=hello&param=world` allowing
  zero values
-* `queryParams: cask.QueryParams` if you want your route to be able to handle arbitrary
+* `params: cask.QueryParams` if you want your route to be able to handle arbitrary
  query params without needing to list them out as separate arguments
+* `segments: cask.RemainingPathSegments` if you want to allow the endpoint to handle
+ arbitrary sub-paths of the given path
 * `request: cask.Request` which provides lower level access to the things that the HTTP
  request provides
 
-If you need to capture the entire sub-path of the request, you can set the flag
-`subpath=true` and ask for a `request: cask.Request` (the name of the param doesn't
-matter). This will make the route match any sub-path of the prefix given to the
-`@cask` decorator, and give you the remainder to use in your endpoint logic
-as `request.remainingPathSegments`
-
 ## Multi-method Routes
 
 $$$httpMethods

example/formJsonPost/app/src/FormJsonPost.scala

@@ -31,5 +31,14 @@ object FormJsonPost extends cask.MainRoutes{
  image.fileName
  }
 
+
+ @cask.postJson("/json-extra")
+ def jsonEndpointExtra(value1: ujson.Value,
+ value2: Seq[Int],
+ params: cask.QueryParams,
+ segments: cask.RemainingPathSegments) = {
+ "OK " + value1 + " " + value2 + " " + params.value + " " + segments.value
+ }
+
  initialize()
 }

example/formJsonPost/app/test/src/ExampleTests.scala

@@ -52,6 +52,12 @@ object ExampleTests extends TestSuite{
  )
  )
  response5.text() ==> "my-best-image.txt"
+
+
+ val response6 = requests.post(
+ s"$host/json-extra/omg/wtf/bbq?iam=cow&hearme=moo",
+ data = """{"value1": true, "value2": [3]}"""
+ )
  }
  }
 }

example/variableRoutes/app/src/VariableRoutes.scala

@@ -31,18 +31,18 @@ object VariableRoutes extends cask.MainRoutes{
  }
 
  @cask.get("/user2/:userName") // allow unknown query params
- def getUserProfileAllowUnknown(userName: String, queryParams: cask.QueryParams) = {
- s"User $userName " + queryParams.value
+ def getUserProfileAllowUnknown(userName: String, params: cask.QueryParams) = {
+ s"User $userName " + params.value
  }
 
- @cask.get("/path", subpath = true)
- def getSubpath(request: cask.Request) = {
- s"Subpath ${request.remainingPathSegments}"
+ @cask.get("/path")
+ def getSubpath(remainingPathSegments: cask.RemainingPathSegments) = {
+ s"Subpath ${remainingPathSegments.value}"
  }
 
- @cask.post("/path", subpath = true)
- def postArticleSubpath(request: cask.Request) = {
- s"POST Subpath ${request.remainingPathSegments}"
+ @cask.post("/path")
+ def postArticleSubpath(remainingPathSegments: cask.RemainingPathSegments) = {
+ s"POST Subpath ${remainingPathSegments.value}"
  }
 
  initialize()

example/variableRoutes/app/test/src/ExampleTests.scala

@@ -112,8 +112,6 @@ object ExampleTests extends TestSuite{
  res3 == "User lihaoyi Map(unknown1 -> WrappedArray(123), unknown2 -> WrappedArray(abc))" ||
  res3 == "User lihaoyi Map(unknown1 -> ArraySeq(123), unknown2 -> ArraySeq(abc))"
  )
-
  }
-
  }
 }