Hiding XPCRouteWith(out)MessageWith(out)Reply from public API.

[amomchilov]

Routes are currently constructed via the public initializers on these route types.

I think the type themselves are useful, because of the way they allow the typesystem to protect from a mismatch between the route type and the sending function.

Perhaps we should use some public factory methods on XPCRoute. We can't fully hide the route types (nor would we want to, because that's what protects against aforementioned mismatches), but they can be tucked away into the return type of the methods, rather than being an explicit part of the written code.

Here's what the call sites might look like:

• XPCRoute.withoutMessage()
• XPCRoute.withoutMessage(withReply: R.self)
• XPCRoute.withMessage(M.self)
• XPCRoute.withMessage(M.self, withReply: R.self)

Thoughts?

[amomchilov]

Related question: as part of #17, should "no reply payload but with an error handler" routes have their own new types (2 new types: XPCRouteWithMessageWithErrorHandler and XPCRouteWithoutMessageWithErrorHandler, totalling 6), or should we just piggy back off the existing XPCRouteWith(out)MessageWithoutReply types.

I think the latter case might be nicer. The client's sending functions can use the existing reply-less route types, and have an optional error-handler. When the error handler is non-nil, the client can encode some metadata into the message that indicates to the server that an error response is welcome. When the server sees this indicator, it will reply with the error (if any).

[jakaplan]

I think there should not be two new route types. Route types are intended to be shared between the client and server. It should be up to the client whether it wants to handle errors for a given call and that shouldn't be reflected in how routes are registered with the server.

[amomchilov]

Agreed.

[amomchilov]

The __route portion of the "outter message"* is defined by the Encodable implementation of XPCRoute. This poses a challenge if there are no "withErrorHandler" Routes.

I did a nasty workaround for this in my fork by intercepting the encoded route object within Request and changing the value of its replyType key to a special string. The server looks for this string and uses it infer that the client wants a error-only reply.

I got the "happy path" (no error to return) working. You can see a PoC here: amomchilov@dfb338d

---

* (not to be confused with the user-defined message... perhaps we need to establish some consistent terminology here. What's the term for the full message sent "over the wire"?)

[amomchilov]

(Out there idea)

I've used this in a different context, but it's possible to use closure types as DSL for expressing the type of inputs/outputs of a process. It leads to this syntax at the call site:

XPCRoute.named("1", signature: (() -> Void).self)
XPCRoute.named("2", signature: (() -> Int).self)
XPCRoute.named("3", signature: (() throws -> Void).self)
XPCRoute.named("4", signature: ((String) -> Void).self)
XPCRoute.named("5", signature: ((String) -> Int).self)
XPCRoute.named("6", signature: ((String) throws -> Void).self)

Each one of these calls a different overload, and can return a different type.

Here's a full self-contained impl

/// A route that can't receive a message and is expected to reply.
public struct XPCRouteWithoutMessageWithReply<R: Codable> {
	let route: XPCRoute
	
	/// Initializes the route.
	///
	/// - Parameters:
	///   - _: Zero or more `String`s naming the route.
	///   - replyType: The expected type the server will respond with if successful.
	public init(_ pathComponents: [String], replyType: R.Type) {
		self.route = XPCRoute(pathComponents: pathComponents, messageType: nil, replyType: replyType, hasErrorHandler: false)
	}
}

/// A route that receives a message and is expected to reply.
public struct XPCRouteWithMessageWithReply<M: Codable, R: Codable> {
	let route: XPCRoute
	
	/// Initializes the route.
	///
	/// - Parameters:
	///   - _: Zero or more `String`s naming the route.
	///   - messageType: The expected type the client will be passed when sending a message to this route.
	///   - replyType: The expected type the server will respond with if successful.
	public init(_ pathComponents: [String], messageType: M.Type, replyType: R.Type) {
		self.route = XPCRoute(pathComponents: pathComponents, messageType: messageType, replyType: replyType, hasErrorHandler: false)
	}
}

/// A route that can't receive a message and will not reply.
public struct XPCRouteWithoutMessageWithoutReply {
	let route: XPCRoute
	
	/// Initializes the route.
	///
	/// - Parameters:
	///   - _: Zero or more `String`s naming the route.
	public init(_ pathComponents: [String], hasErrorHandler: Bool = false) {
		self.route = XPCRoute(pathComponents: pathComponents, messageType: nil, replyType: nil, hasErrorHandler: hasErrorHandler)
	}
}

/// A route that receives a message and will not reply.
public struct XPCRouteWithMessageWithoutReply<M: Codable> {
	let route: XPCRoute
	
	/// Initializes the route.
	///
	/// - Parameters:
	///   - _: Zero or more `String`s naming the route.
	///   - messageType: The expected type the client will be passed when sending a message to this route.
	public init(_ pathComponents: [String], messageType: M.Type, hasErrorHandler: Bool = false) {
		self.route = XPCRoute(pathComponents: pathComponents, messageType: messageType, replyType: nil, hasErrorHandler: hasErrorHandler)
	}
}


struct XPCRoute {
	let pathComponents: [String]
	let messageType: Any.Type?
	let replyType: Any.Type?
	let hasErrorHandler: Bool
}

extension XPCRoute {
	static func named(_ name: String..., signature: (() -> Void).Type) -> XPCRouteWithoutMessageWithoutReply {
		print("\(name): I have no message payload and no reply payload.")
		return XPCRouteWithoutMessageWithoutReply(name, hasErrorHandler: false)
	}
	
	static func named<R: Codable>(_ name: String..., signature: (() -> R).Type) -> XPCRouteWithoutMessageWithReply<R> {
		print("\(name): I have no message payload and a reply payload (\(R.self)).")
		return XPCRouteWithoutMessageWithReply(name, replyType: R.self)
	}
	
	static func named(_ name: String..., signature: (() throws -> Void).Type) -> XPCRouteWithoutMessageWithoutReply {
		print("\(name): I have no message payload  and an error handler.")
		return XPCRouteWithoutMessageWithoutReply(name, hasErrorHandler: true)
	}
	
	static func named<M: Codable>(_ name: String..., signature: ((M) -> Void).Type) -> XPCRouteWithMessageWithoutReply<M> {
		print("\(name): I have a message payload (\(M.self)) and no reply payload.")
		return XPCRouteWithMessageWithoutReply(name, messageType: M.self, hasErrorHandler: false)
	}
	
	static func named<M: Codable, R: Codable>(_ name: String..., signature: ((M) -> R).Type)  -> XPCRouteWithMessageWithReply<M, R> {
		print("\(name): I have a message payload (\(M.self)) and a reply payload (\(R.self)).")
		return XPCRouteWithMessageWithReply(name, messageType: M.self, replyType: R.self)
	}
	
	static func named<M: Codable>(_ name: String..., signature: ((M) throws -> Void).Type) -> XPCRouteWithMessageWithoutReply<M> {
		print("\(name): I have a message payload (\(M.self)) and an error handler.")
		return XPCRouteWithMessageWithoutReply(name, messageType: M.self, hasErrorHandler: true)
	}
}

_ = XPCRoute.named("1", signature: (() -> Void).self)
_ = XPCRoute.named("2", signature: (() -> Int).self)
_ = XPCRoute.named("3", signature: (() throws -> Void).self)
_ = XPCRoute.named("4", signature: ((String) -> Void).self)
_ = XPCRoute.named("5", signature: ((String) -> Int).self)
_ = XPCRoute.named("6", signature: ((String) throws -> Void).self)

Just dropping this as a little "in case you're curious" because I thought it was neat. I wouldn't necessarily recommend it, though :)

[jakaplan]

This is intriguing, but less easily understood than what you originally proposed. So I agree with your non-recommendation :)

[jakaplan]

Perhaps we should use some public factory methods on XPCRoute. We can't fully hide the route types (nor would we want to, because that's what protects against aforementioned mismatches), but they can be tucked away into the return type of the methods, rather than being an explicit part of the written code.

Thoughts?

What's the problem that's trying to be addressed with this? Is it that at the call site this approach is a bit more concise? If so, yes I can see some appeal to that.

[amomchilov]

Here's what the style from the top post might look like: amomchilov/SecureXPC@add-message-sending-integration-test...amomchilov:hide-route-type-names/approach-1#diff-1d0119acaf113027616db5ae088a57770b607260d6911dc23b22d29fd2c82c54

And the builder-style: amomchilov/SecureXPC@add-message-sending-integration-test...amomchilov:hide-route-type-names/approach-2#diff-1d0119acaf113027616db5ae088a57770b607260d6911dc23b22d29fd2c82c54

[jakaplan]

Hmm, neither of those links seem to work properly unless I'm misunderstand how they're supposed to work. This is what I see when I click on them (it's the same for both links):

[jakaplan]

There's also a builder style like:

[elided]

It has the best call-site IMO, but the implementation is a bit longer (idk how you feel about that).

I agree the call site looks quite nice once actually written. I'm concerned the documentation for this would end up looking quite confusing though and therefore API users would struggle to figure out how to properly use it. In order for: XPCRoute.named("foo").withMessage(String.self).withReply(Foo.self) to work that'd mean the type returned by XPCRoute.named("foo").withMessage(String.self) would need a withReply(...) function and that seems pretty unintuitive even though once fully written out it's pretty straightforward.

My experience with builder patterns is you always get back the same type (well under the hood it could differ, but same exposed type) once you've finalized it with a function like build() and prior to that you get back the builder instance itself. With that pattern, the resulting documentation is quite clear. Unfortunately because we need to return four different types that wouldn't work for us.

That leads me to think that this is a really intriguing idea, but ultimately too "clever".

[amomchilov]

Huh, I think that's a bug in GitHub! It mangles out the # in the urls.

Try these:

1. "normal" style
2. "builder" style

---

I'm concerned the documentation for this would end up looking quite confusing though and therefore API users would struggle to figure out how to properly use it.

I thought about this, but wasn't ultimately too worried because it would be the kind of thing that appears prominently in the readme anyway

I'd just note one example of teeny tiny niche example of a builder pattern similar to this: all of SwiftUI. Heh, sarcasm aside, I think it's done a good job in "training" devs to look for "modifiers" that can be called on return values, so I think this would be decently in-line with expectations.

What draws me most to it is that it breaks apart the with(out)Message and with(out)Reply portions into two separate functions, each of which can be more reliably fuzzy-matched by Xcode's auto-completion. With the other approach (or with the current approach of just calling initializes on the types), the fuzzy matching is thrown off by the repetition of with(out), so you have remember to over-specify characters to nail down the correct variant.

[jakaplan]

I'd just note one example of teeny tiny niche example of a builder pattern similar to this: all of SwiftUI.

I'm not familiar with SwiftUI (as in, I know what it is - but I haven't personally used it). I just spent ~15 minutes looking through the documentation, and couldn't quite find an equivalent to what you were describing but absolutely saw chaining all over the place.

Alright - let's give this approach a go. Definitely important to get the documentation right.