Removing idle state

[ianthetechie]

Background

When implementing TripState, I envisioned it as an enum with 3 variants: idle, navigating, and complete. The first and last variants contain no data but are merely markers that indicate an initial or terminal state.
It was originally envisioned that apps would always keep some TripState around as a signal of what FerrostarCore was doing.

Problems

Over time, we've identified a few problems in this approach.

For one, it is confusing since now there are multiple possible ways of representing an "initial" state. Both the idle variant and null/nil are valid representations, depending on your view model/observable/similar state data structures. This is further complicated by the fact that you may not have even had a good reason to initialize FerrostarCore at the point your view is created, so devs would need to hack up a zero-argument constructor that constructs an idle state when null would do.

It's also ambiguous when state should ever reset to idle. This is something you would have to manually do (again, constructing a state value) in your view model at some point. FerrostarCore will never emit an idle variant by itself, so it's not very clear to users how this is intended to be used. Over time the included defaults, demo view models, and so on that we've shipped with Ferrostar have migrated to prefer nil/null as a signal that no navigation is currently in progress or recently finished (this was a move I wasn't entirely sure of at the time @Archdoog proposed it, but in the past few months I've come to agree with the decision).

Proposal: Remove the idle variant, but keep completed

As such, I propose we remove the idle variant. This will necessitate some app changes, but it also seems to me like it clarifies things a bit for discussions like #275. The "non-navigation" modality of the map is active only when the tripState is null/nil.

The completed state still seems useful to me, since many apps have "post-trip" flows. This provides a useful third state between "Ferrostar is completely inactive" and "Ferrostar isn't doing anything, but it did complete a trip." App developers can then decide when it's appropriate to clear that state.

Tangential item for discussion: We're also considering event hooks for things like "trip started" and "trip ended." I haven't had the head space to collect thoughts on that into a coherent doc, but if anyone is so inclined, have at it :)

[hactar]

Adding some thoughts/questions:

• I think the first choice that needs to be made is is TripState a total application state, or a state during a trip. If its a total application state it could also include a idle/notNavigating state, but I do think that would be weird, as nothing would prevent me from putting ferrostar into an "isNavigating" state, while not actually being able to navigate because there might not be any waypoints
• Do we want tripstate to be a derived state, or do we want it to be a setable state, or both. I think this is more of a derived state, so could be navigating, completed. Other derived states that might be interesting are things like "rerouting", where devs might want to tie UI into. same goes for things like "inTunnel".
• Then there's interesting "setable" state too: .paused was always a heavily requested feature in all nav apps, where when you're taking a break, you can pause navigation, conserving battery.

As mentioned the "difficulty" will be that many of these states are not mutually exclusive. While you're paused, you're still navigating. You could be in a tunnel while rerouting. I have no suggestion for an architecture for this, just throwing it in as food for thought :) - But yes, I do not see a clear benefit of the idle state, especially if ferrostar doesn't set it. Completed sounds useful.

[ahmedre]

My $0.02 (and this is just my personal preference, take with a massive grain of salt) - I personally prefer TripState to be navigation only, since a full application state will not be "one size fits all" - the example of a delivery app, where there's an "on arrive to waypoint" task of either "wait for the food to be prepared," or "upload a picture of the food before continuing navigation to another pick up" - is quite different from the example of a navigation app. Keeping it as navigation only would make it easier for people to augment the existing state machine to fit their needs.

re: derived or setable - imho, derived and folks can augment to handle things like rerouting (and for the pause idea). It'd theoretically handle tunnel mode also if we have the data to tell us we're in a tunnel, since, by listening to the state transition and noting that I am in a tunnel, I can update my state to be "in a tunnel," etc.

[ianthetechie]

Purpose of TripState

It's pretty clear in my mind that this can only every be within the context of "what is going on during a trip / what is the state of FerrostarCore." I have some borderline crazy ambitions for Ferrostar, but encapsulating total application state is one that I don't believe Ferrostar can/should solve ;)

Derived vs settable state (and other things)

This is also pretty clearly derived to me. I love that you bring up other things like "are we rerouting" though. This is almost a trick question ;)

Things like "are we recalculating" will probably never live in TripState. This is a higher level (FerrostarCore at the platform layer, not Rust) for a few reasons (the biggest being that we want to keep the core as simple and functionally pure as possible, pushing interior mutability one layer up). This specific attribute is already captured in

ferrostar/apple/Sources/FerrostarCore/NavigationState.swift

Line 16 in adb74ca

public internal(set) var isCalculatingNewRoute: Bool = false

.

I think we'll also eventually figure out ways to model and surface things like "are we in a tunnel" too. This could be anything from general attributes (rather like annotations?) to local map matching to remote attribute fetching along the upcoming section of route. Ideas welcome; I have a background task thinking about this too.

"Settable" state (specifically paused)

I think we can handle paused with only a few modifications to how things work today. @Archdoog also mentioned wanting this too. It feels like in this case, the state of being paused is not at the same level as a TripState variant. You are still "on a trip" and all of the other state (remaining steps, route geometry, etc.) still applies. You have just paused things like (maybe?) location updates, determination of whether the user is off route, perhaps stopped sending updates to the navigation controller, etc...

Maybe one of you can open an issue on that so we can discuss what it should look like? I'm not sure what "paused" means myself besides "not progressing / processing location inputs in the usual way."

As mentioned the "difficulty" will be that many of these states are not mutually exclusive

I think that TripState variants should be mutually exclusive, but many other states (ex: recalculating, paused, etc.) may not. And I think most of these lie at the app level rather than the framework. Therein lies the whole balance of choosing enums vs structs for state modeling.

But yes, I do not see a clear benefit of the idle state, especially if ferrostar doesn't set it. Completed sounds useful.

👍

[ahmedre]

More recently, I have been thinking of FerrostarCore as a sort of state machine - one that manages various state transitions within navigation. Considering that every company has different requirements for what they're building, the nice thing about this is it allows people to do their own thing - transitioning between different state machines or augmenting states from the Ferrostar state machine. For example, we use the "default" state today to handle route previews. Anything before route previews is handled by a separate state machine that emits the proper state for what the person sees on the screen (things like details about search, points of interest, etc).

I think the current architecture makes it possible to implement the pause mode @hactar suggested, for example, by combining the navigation state with something from the overall application state to have an overall state of either paused or navigating (assuming that methods to enable/disable location services during a trip).

[ianthetechie]

More recently, I have been thinking of FerrostarCore as a sort of state machine...

:D That's fantastic; because that's exactly how we think of it too :) Actually, to get slightly more in the weeds, we view the Rust layer (NavigationController, TripState, and related concepts) as a functionally pure finite state machine. FerrostarCore is a very slightly relaxed version of this since it's allowed to have internal mutable state to make it easier to work with, but we're trying to keep the same mental model.

I think the current architecture makes it possible to implement the pause mode @hactar suggested, for example, by combining the navigation state with something from the overall application state to have an overall state of either paused or navigating (assuming that methods to enable/disable location services during a trip).

Yup, I think that's correct. I think it's already possible (or very close to it) and I'd welcome a discussion topic or issue to discuss what this looks like from anyone who has opinions.