Support cookie parameters

[czechboy0]

There is some existing support as part of parameters, but we should add an example into the reference test, and ensure the usage is ergonomic.

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-locations

[sliemeobn]

There is some existing support as part of parameters

At least on the server side I could not find a way to access cookie parameters in the generated request handlers. I can probably work my way around this by using some TaskLocal construct via a middleware, but it sure would be nice to just have typed access in the route handler (or maybe just access to the "raw" request for any not implemented feature yet?)

Use case: A refresh-token endpoint that uses a httpOnly cookie for the actual refresh token (so it's just for that one route).

[simonjbeaumont]

@sliemeobn thanks for adding your feedback here. It's very useful as we want to prioritise the features based on demand from the community.

This shouldn't be too challenging if someone wants to pick it up, as it will likely be similar to other parameters.

but it sure would be nice to just have typed access in the route handler (or maybe just access to the "raw" request for any not implemented feature yet?)

I don't think we've ever discussed adding an escape hatch because things can usually be worked around in middlewares (as you noted), but maybe we could consider it (would be underscored and subject to removal).

What do you think such an API would look like?

Currently the APIProtocol declares the operations as functions from the Input to Output type and has no knowledge of the HTTP request or response. This protocol is used on the client and server sides. The ServerTransport obviously has access to more information, but it's not clear how we'd get that to the "user function" for the handler implementation, without breaking the symmetry of protocol use on client and server.

[czechboy0]

To help us all iterate here, @sliemeobn could you paste a short snippet of the cookie parameter definition in YAML here? We can then discuss what the generated code should look like on the client and server.

[sliemeobn]

Here is the OpenApi snippet of the route I was referring to (I am setting the cookie in a /login route)

  /refresh-token:
    post:
      operationId: refreshToken
      description: Returns a new access token and optionally changes the station. (for renewal or station change)
      parameters:
        - in: cookie
          name: refreshtoken
          schema: { type: string }
        
      requestBody:
        required: true
        content:
          application/json: 
            schema:
              type: object
              required: 
               - station
              properties:
                station: { type: string }

[czechboy0]

I am setting the cookie in a /login route

Can you elaborate on that? Are you saying that the call sequence is the following?

1. Call /login route with some other auth method, get back a refresh token that you store locally
2. Call /refresh-token with an optional refreshtoken cookie (what happens if it's not specified?) using the token from the previous call, possibly getting back another cookie value? Is that cookie coming back documented in the OpenAPI doc?

[sliemeobn]

The /login just takes user/password (and station, application specific stuff) as a payload. It returns a short-lived token (for API access) and a Set-Cookie: refershtoken=xxx for renewal (refreshToken with longer expiry).

The application will then renew the access token without requiring a password.
Obviously, it does not have to be done that way, but a scoped httpOnly cookie is quite a good place to store this.

  /login:
    post:
      operationId: login
      requestBody:
        required: true
        content:
          application/json: { schema: { $ref: "#/components/schemas/Login"} }
      responses:
        "200":
          description: Success
          headers:
            Set-Cookie: { schema: { type: string } }
          content:
            application/json: { schema: { $ref: "#/components/schemas/TokenResponse" }}
        "401":
          description: Unauthorized

[czechboy0]

Gotcha, and the /refresh-token response also has the following?

headers:
    Set-Cookie: { schema: { type: string } }

Just trying to understand the invocation, and how much could be generated and shared between all users of cookies, and how much we should instead put into middlewares 🙂

[sliemeobn]

At the moment the refreshtoken is only issued on /login - when it expires, a password is needed. So /refresh-token will not set a new one.

[sliemeobn]

About the "escape hatch", I am currently playing around with this:

/// Extensions to work around current limitiation on OpenAPI generator
enum RawRequest {
    @TaskLocal static var current: OpenAPIRuntime.Request?
}

/// Make RawRequest.current available as a task-local.
struct RawRequestMiddleware: ServerMiddleware {
    public func intercept(_ request: OpenAPIRuntime.Request, metadata: OpenAPIRuntime.ServerRequestMetadata, operationID _: String, next: (OpenAPIRuntime.Request, OpenAPIRuntime.ServerRequestMetadata) async throws -> OpenAPIRuntime.Response) async throws -> OpenAPIRuntime.Response {
        try await RawRequest.$current.withValue(request) { try await next(request, metadata) }
    }
}

I general, I was thinking about how most web server frameworks provide some form of "storage" on their request structure for attaching all sorts of things and passing around this unwieldy thing down the pipe. But as this was all conceived before structured concurrency and TaskLocals, and I quite like the "clean" functional way of the generated handler being all "you can only do what you define in the spec!".

But without storage on the request, it'll be tough to use middleware to "pre-process" requests in some reusable form without TaskLocals... So, not sure if that ends up being any better. 🤔

[czechboy0]

Right, what you have is roughly what I had in mind.

One difference is that I'd make the middleware extract the value you're interested in, validate it, etc, and then put it into a task local.

If you think about how you'd then test your handler, it'll be easier to inject a specific value instead of having to create a whole request.

Once cookies are supported more properly, I'd expect them to show up on the Input struct, just like all the other parameters.