Support incidents for OSRM responses

[ahmedre]

This parses incidents on the OSRM response route leg, and splits the
incidents across the corresponding route step. Since an incident may
span multiple steps, this will duplicate an incident and adjust the
indices accordingly whenever that happens. Clients can de-duplicate
these if necessary based on the incident identifier.

[ahmedre]

i need to fix this - this shouldn't be all the items, just the items relevant to this step.

[ahmedre]

fixed, but please see the discussion below for some trade-offs.

[ahmedre]

@ianthetechie would appreciate your input here, since we have a few possible solutions that we were discussing internally, each with their set of pros and cons (we chose one of the solutions for this PR) - but want to know what you'd recommend.

The Problem

Mapbox's SDK emits incidents on the leg instead of on the step. While this is similar to the case of how annotations are handled, there are differences. For example, unlike annotations, where geometry.size == annotations.size for the overall route, the incidents array is not one to one with either since it's really a set of events that occur on this path. Consequently, a given incident may (theoretically anyway, the documentation is sparse about this) span multiple steps. This brings about the complication.

Possible Solutions

Incidents on Legs

Keep incidents on the leg instead of on the step (i.e. on TripState.Navigating in this case). Since the steps are dynamic but the global routeGeometry is not going to change, this means we'd need to hydrate information that helps people using the api to map a given incident to the proper relevant RouteSteps (i.e. if we just say starts at routeGeometry index 3000 and ends at routeGeometry index 3050, I have no idea which RouteStep that corresponds to - has it passed? Is it up ahead?) We'd need something to say "the current RouteStep is at index x of the overall routeGeometry for such calculations to be feasible.

• Pros - it's modeled like the api models it.
• Cons - we'd need to expose currentStepRouteGeometryStartIndex, which is kind of unfortunate. It is also cumbersome for customers to make use of this data, since they would still need to do calculations from there to figure out which RouteSteps this applies to.

Incidents on Routes

Keep incidents on the RouteStep depending on the corresponding geometry_index_start (and, if present geometry_index_end). This is the approach taken by this patch. If a particular Incident spans multiple RouteSteps, this will duplicate the Incident, and adjust the indices accordingly. For example, if an Incident is starts in step 3 at index x and ends in step 4 at index y, this would result in 2 copies of the Incident - one in step 3 between the mapped x to the end of step 3's indices, and one in step 4 between 0 and the mapped end. If it had spanned another step, there would be an additional copy spanning the entire middle step.

• Pros - it's in line with what's there today, and is easier for clients to work with.
• Cons - duplicating Incidents means clients would need to de-dup them if necessary to avoid re-notifying, etc.

[ahmedre]

also, i am not sure why ios CI fails with:

fatal: invalid reference: support_incidents

[ianthetechie]

Ahh... yeah, that's because of a (semi-controversial) CI step I added a while ago. I think it's annoying when CI rejects changes it can fix for you, so I added a step that runs swiftfmt (EDIT: And checks Package.swift for local development configurations and commits changes you forgot about in ferrostar.swift) and commits any changes rather than failing, but this just fails with a confusing error on cross-org forks 💀 I guess I'll probably revert that eventually and make the author push a fix.

[ahmedre]

I updated the PR to use from as you mentioned last week.

Also, took a look at TomTom's results - they have:

        {
          "startPointIndex": 3,
          "endPointIndex": 4,
          "sectionType": "TRAFFIC",
          "simpleCategory": "JAM",
          "effectiveSpeedInKmh": 40,
          "delayInSeconds": 158,
          "magnitudeOfDelay": 1,
          "tec": {
            "effectCode": 4,
            "causes": [
              {
                "mainCauseCode": 1
              },
              {
                "mainCauseCode": 26,
                "subCauseCode": 2
              }
            ]
          }
        },

so while there are common points with the OSRM api, it's quite far from it, since that structure itself is in a sections section that seems to be the equivalent of the OSRM annotation block. so even if we did what we discussed last week (pulling out common items and keeping the json for people to parse depending on the usage), it seems as though we still couldn't parse this type of format returned from TomTom without some changes since their format is not really OSRM compliant.

[ianthetechie]

Yeah... I agree with your assessment. Sorry it took me a while to get back to this; was buried in geocoding pipelines last week 😅

I think that we can go ahead and merge this + figure out any refinements/generalizations to the data models later once someone has a motivating use case. You're currently using Mapbox or a compatible API, and we would probably be doing the same at Stadia Maps. And since most things are optional, I think that we can go with the "superset" model approach and don't actually need the full dynamism that we built for annotations (annotations could be pretty arbitrary and use case-specific; incidents, not so much).

[ianthetechie]

I think we can simplify all this manual work with a snapshot test; I'll handle that real quick.