Swift API for callable functions

[mortenbekditlevsen]

Hi all,

Adding encoding and decoding support - and async/await to the callable api is pretty straight forward and there's a PR in place at: #8854

But the API could perhaps be made a bit 'stronger': A callable function is generally parametrized by three things: A name for the callable, the type of the encodable request and the type of the decodable response.

This means that you could create a protocol whose conforming types would correspond to the definition of a callable function:

public protocol CallableType {
    associatedtype RequestType: Encodable
    associatedtype ResponseType: Decodable
    static var name: String { get }
}

(or CallableDefinition or some other name)

Defining your callables through this API gives more type safety (less risk of accidentally creating typos at the point of use, or using other data than the expected for either request or response).

Example of the usage of the API defined in the PR versus one with tighter typing - and here I'm using the async/await versions of the API because they are a bit simpler to type out, but the same of course applies for non-async/await API:

Current:

    let request: (some encodable entity)
    let callable = Functions.functions().httpsCallable("calculatePi")

    return try await callable.call(request, resultAs: CalculatePiResponse.self)

versus the suggested:

struct CalculatePi: CallableType {
    typealias RequestType = CalculatePiRequest
    typealias ResponseType = CalculatePiResponse
    static var name: String = "calculatePi"
}


...

    let request: (some encodable entity)
    let callable = Functions.functions().httpsCallable(CalculatePi.self)
    return try await callable.call(request)

In the latter, the compiler enforces that request must be a CalculatePiRequest and it returns a CalculatePiResponse.

My question for discussion is:
Should this more opinionated API be made available?
Should the less opinionated API be discouraged (by not adding codable extension to it)
Should we leave the less opinionated API as the only option since it resembles the underlying API more closely.

In my own code I love to have strong typing and less opportunity for errors by defining these kinds of 'schema'-types. I do the same for RTDB and Firestore. So personally I'd go for adding the 'type safe' API and not adding codable extensions to the existing API.

What do you think?

One extra addition could be to use the 'callAsFunction' functionality so that you don't require the extra .call on a callable, but you can treat it as a function...

[mortenbekditlevsen]

To expand on the last comment above:

If we use callAsFunction as the function name instead of call then you can simply use the Callable as a function:

public struct Callable<C: CallableDefinition> {
    private let functions: Functions
    internal init(_ functions: Functions) {
        self.functions = functions
    }
    public func callAsFunction(_ data: C.Request,
              encoder: StructureEncoder = StructureEncoder(),
              decoder: StructureDecoder = StructureDecoder(),
              completion: @escaping (Result<C.Response, Error>)
                -> Void) throws {
        try functions
            .httpsCallable(C.name)
            .call(data,
                  resultAs: C.Response.self,
                  encoder: encoder,
                  decoder: decoder,
                  completion: completion)
    }

#if compiler(>=5.5) && canImport(_Concurrency)
  @available(iOS 15, tvOS 15, macOS 12, watchOS 8, *)
    public func callAsFunction(_ data: C.Request,
                   encoder: StructureEncoder = StructureEncoder(),
                   decoder: StructureDecoder =
                     StructureDecoder()) async throws -> C.Response {
        try await functions
            .httpsCallable(C.name)
            .call(data, resultAs: C.Response.self)
  }
#endif

}

Point of use:

    let callable = Functions.functions().callable(for: CalculatePi.self)
    let piResponse = try await callable(CalculatePiRequest(numberOfDecimals: 1))

[mortenbekditlevsen]

Apologies for the slight refactor in my code above from the one suggested earlier - I renamed CallableType to CallableDefinition and removed Type from RequestType and ResponseType associated values...

[mortenbekditlevsen]

@peterfriese @paulb777 @IanWyszynski Just tagging you in case you would find this discussion interesting. 😊

[peterfriese]

@schmidt-sebastian, too.

[mortenbekditlevsen]

Hi all,
@schmidt-sebastian had an excellent suggestion with an API that sits somewhere in the middle between the strongly typed, but requiring quite a bit of ceremony, and the existing implementation:

let callable = functions.httpsCallable("HelloWorld", encoder: Foo, decoder: Bar);
callable.call(data);

Thus removing the requirement for specifying the return type at the call site and eliminating calls with unintended data, but supplying the types directly to httpsCallable(...) instead of my suggestion for wrapping the callable name and types in a type of it's own.

Thank you for the suggestion, Sebastian. I'll go ahead and close the discussion, but if anyone has further comments you are of course welcome to reopen it.

[mortenbekditlevsen]

Oh, you can't close a discussion. I'll leave it here for future reference then. :-)