Changing the client configuration

[lukeredpath]

I'm curious how you would change the base configuration of the URLRoutingClient after you've created it with the current design.

The router has APIs for setting the base URL and base URL request data - the latter is useful for setting things like default headers. How would you deal with something that can change throughout the course of an app's lifetime like authentication? How would you set custom headers on the client itself as there is no API to manipulate the router after its constructed. Would you just create a new client?

[lukeredpath]

Just playing around with the ideas of implementing API client authentication using routing. Given my question above I'm unsure about the ergonomics of the final result though.

Firstly we could define some kind of wrapper for our route that layers on authentication:

enum Authorization {
    case bearer(String)
}

struct Authenticated<R> {
    let authorization: Authorization
    let route: R
}

In this example, we define an enum type representing possible "Authorisation" header values - in this example we just have a bearer token - we could extend this to support other types. We can define a parser that wraps a parser for our main route R and returns an Authenticated<R>:

extension Authorization {
    static let parser = OneOf {
        Parse(.case(AuthenticationMethod.bearer)) {
            "Bearer "
            Parse(.string)
        }
    }
}

extension Authenticated {
    static func parser<RouteParser: ParserPrinter>(
        authenticating routeParser: RouteParser
    ) -> AnyParserPrinter<URLRequestData, Self>
    where
        RouteParser.Input == URLRequestData,
        RouteParser.Output == R
    {
        Route(.memberwise(Authenticated<R>.init)) {
            Headers {
                Field("Authorization") {
                    Authorization.parser
                }
            }
            routeParser
        }
        .eraseToAnyParserPrinter()
    }
}

extension ParserPrinter where Input == URLRequestData {
    /// A convenience method that turns an existing router into an authenticated router.
    func authenticated() -> AnyParserPrinter<URLRequestData, Authenticated<Output>> {
        Authenticated.parser(authenticating: self)
    }
}

With this in place, we can now create a client with authorization support:

enum SiteRoute {
  case example
}

extension SiteRoute {
  static let router = OneOf {
    // ...
  }
}

let client = URLRoutingClient.live(router: SiteRoute.router.authenticated())

Now we can perform authenticated requests:

try await client.request(.init(authorization: .bearer("token"), route: .example))

This isn't bad but it would be annoying to have to create a full authenticated route with the token each time. We can create a helper that turns a client of authenticated routes into a client of just routes that wraps this behaviour up for us:

extension URLRoutingClient {
    func authenticated<R>(
        using authorization: Authorization
    ) -> URLRoutingClient<R> where Route == Authenticated<R> {
        .init {
            try await self.request(.init(authorization: authorization, route: $0) )   
        }
    }
}

Now we can easily make authenticated requests:

let authedClient = client.authenticated(using: .bearer("token"))
try await authedClient.request(.example)

In terms of ergonomics, I try to imagine how I might use this in say, a TCA app. My app can switch between a logged out and a logged in state. There are some routes that I need to make without an authorization header (e.g. the login routes) so I need an unauthenticated client in my root environment and once the user is logged into the app, I need to pass around an authenticated client. I might also need to periodically refresh an access token and update the client but I can't think how I'd do that with the above API. Anyone got any thoughts?

It sounds like I need some kind of intermediate layer that manages the base API client and current authentication state so it can update the authenticated client when the authentication state changes.

[lukeredpath]

I've been thinking about this some more and I'm thinking that the concept of an "authorized" route should form a core part of your route modelling. For example, given an API with a /login endpoint (doesn't require authorization, but authenticates credentials and exchanges them for a token), a public non-authorized endpoint /about and then a bunch of account endpoints that do require authorization and for you to login, they could be modelled as:

enum SiteRoute {
  case login(Credentials)
  case about
  case account(Authorized<AccountRoute>)
}

enum AccountRoute {
  case settings
  case changePassword(ChangePasswordRequest)
}

I'm repurposing the Authenticated type in my post above, renamed here to Authorized as I think that's more semantically correct. We can tweak the authorization parser to be a bit more general:

extension Authorized {
    static func parser<RouteParser: ParserPrinter>(
        @ParserBuilder _ routes: () -> RouteParser
    ) -> AnyParserPrinter<URLRequestData, Self>
    where
        RouteParser.Input == URLRequestData,
        RouteParser.Output == R
    {
        Route(.memberwise(Authorized<R>.init)) {
            Headers {
                Field("Authorization") {
                    Authorization.parser
                }
            }
            routeParser()
        }
        .eraseToAnyParserPrinter()
    }
}

We can now define our site router with the concept of authorization baked right in:

extension SiteRoute {
  let parser = OneOf {
    Route(.case(SiteRoute.login)) {
      Path { "login" }
      Method.post
      Body(.json(Credentials.self))
    }
    Route(.case(SiteRoute.about)) {
      Path { "about" }
    }
    Route(.case(SiteRoute.account)) {
      Authorized.parser {
        Path { "account" }
        OneOf {
          Route(.case(AccountRoute.settings)) {
            Path { "settings" }
          }
          Route(.case(AccountRoute.changePassword)) {
            Path { "password" }
            Method.put
            Body(.json(ChangePasswordRequest.self))
          }
        }
      }
    }
  }
}

With this approach, the main API client becomes:

let client = URLRoutingClient<SiteRoute>.live(router: SiteRoute.router)

// We can make a public request
try await client.request(.about) // OK

// We can login to get an auth token
let result = try await client.request(.login(.init(email: "[email protected]", password: "password")), as: AuthResponse.self)

// Now we can make authorized requests
let authorization = Authorization.bearer(result.response.token)
let settings = try await client.request(.account(.init(authorization: authorization, route: .settings)))

// We can make this a bit easier by creating a pre-authorized "account" client.
// Could some kind of general pullback/scope function make this easier?
extension URLRoutingClient where Route == SiteRoute {
  /// Returns a client scoped to making authorized account requests.
  func account(token: String) -> URLRoutingClient<AccountRoute> {
    .init { self.request(.account(.init(authorization: .bearer(token), route: $0))) }
  }
}

let accountClient = client.account(token: result.response.token)

// Now we can request account routes easily
let settings = try await accountClient.request(.settings)

I like that this idea can be extended quite easily as you can use the Authorized type for any route that requires it. You could do:

enum SiteRoute {
  case foo(Authorized<FooRoute>)
  case bar(Authorized<BarRoute>)
}

Or you could bundle up all of your authorized routes together:

enum SiteRoute {
  case public(PublicRoute)
  case private(Authorized<PrivateRoute>)
}

enum PublicRoute {
  // ...
}

enum PrivateRoute {
  // ...
}

[lukeredpath]

@stephencelis @mbrandonw if you'd be willing to accept a pull request, I'd be happy to start one to explore these ideas a bit further. I'm thinking there are three core components:

• Some domain types - Authorization to model the auth header and Authorized<R> for modelling authorized routes.
• Parsers for the above - my Authorized.parser helper should probably be promoted to a full parser printer implementation to avoid the use of eraseToAnyParserPrinter().
• The extended authorization and setAuthorization API with a modification to the live implementation to track this state.

I've been thinking about this purely from a client perspective but I guess there's no reason why all of this wouldn't work on the server - you define protected routes using Authorized and your route handler can inspect the token and verify it just as it normally would. Even better, you don't even need to manually pluck it out of the HTTP headers as its already been extracted into a domain-specific value type.

[stephencelis]

Thanks for starting the discussion! Client state like authentication is definitely a deficiency we knew about at the time of open sourcing, but we haven't come up with a solution yet and were even hoping for community engagement like this to help introduce ideas around it.

We'd definitely be interested in test-driving draft PRs that attempt to tackle the problem! We're still thinking through the problem space, so we're just not sure that we're ready to merge a solution to a problem before we more fully understand it.

A few thoughts:

1. Many of the ideas in URLRoutingClient were born out of the isowords API client. However, due to authentication and other state (the current player), we weren't able to adopt URLRoutingClient there yet without additional friction.
2. The Authorization types (and others) in your code sample above will be interesting to flesh out. What domain-specific means of authorization will be available and how will they be extensible? Do you have visions for Basic vs. OAuth (1.0 and 2.0), refresh tokens, JWT, etc.?
3. Is it possible to extend the URLRoutingClient externally to begin to test these ideas? I think it might be possible to capture some additional logic and state in a new static func that calls out to the existing live endpoint, but I'm not sure if you'll bump into limitation or friction there.
4. One other thing that Brandon and I wondered while thinking about this problem is if it's getting into too much nitty gritty customization to work into this layer. We sketched out a wrapper type that held onto URLRoutingClient and managed authorization. This worked, but was admittedly messy and the extra layer didn't feel great.

Those are just a few immediate things that come to mind. If I think of anything else I'll try to follow up!

[lukeredpath]

Hey Stephen, to respond to your points:

• I think it's important to keep the scope quite narrow at the moment. Specifically I think its important to separate the concepts of authentication (proving who you are) and authorization (proving you have the right to perform a request). There are lots of different ways an app can handle authentication (login with credentials, OAuth etc.) which I think should mostly be outside the scope of what URLRoutingClient does as its quite often app-specific. But in terms of HTTP requests, you generally perform authorized requests by either setting a header (normally "Authorization" but it could be a custom x- header) or sometimes you pass an API token in the parameters.
• As it stands, I don't think it's possible to extend URLRoutingClient to include these kind of APIs without some additional API surface unless you wrap it in a separate type that manages the authorization state. I also considered this approach but as you say, its a bit messy.

I think at the very least the library needs to support an Authorization type, APIs to set and get the current authorization and some built-in parsers. I think without adding a new generic that lets users define their own Authorization type, it should still be possible to support most types of auth header, as well as tokens in query strings and custom headers:

enum Authorization {
  case basic(username: String, password: String) // "Authorization: Basic <value>"
  case bearer(token: String) // "Authorization: Bearer <token>"
  case param(key: String, value: String) // e.g. "?api_key=foo"
  case customHeader(header: String, value: String) // et.c. "X-Custom-Auth: <value>"
}

This can support anything that can be parsed and printed to a URL request.

With this API available, the Authorized<R> stuff could be implemented in a third-party library to start with. Maybe a starting point would be a draft PR that adds the above and then I could put together an example implementation in a separate package.

[lukeredpath]

Some early experimentation here main...lukeredpath:authorized-clients.

I had a realisation while working on this that the Authorization cases only needed to hold the parsed token (if there is one) - the header name, or query param name needs to be passed into the parser so it knows what field to parse.

I'm quite happy with it so far, I'm less sure about how the definition of the failing client should handle the authorization and setAuthorization functions and some more thought is needed around the ergonomics of testing.

[saroar]

@stephencelis any update about @lukeredpath pull request? or you have any solution for coming soon ?