Accept request URL in lieu of configuration file

[1ec5]

Overhauled the command line tool’s configuration option. Instead of the --config option that takes a JSON configuration file path, the tool now takes a single positional argument that can either be a JSON configuration file path or a Directions API or Map Matching API request URL. When you pass in a request URL, the URL is round-tripped through a DirectionsOptions object back to a URL, exercising the entire typical code path (and then some).

But if you do decide to pass in a JSON configuration file instead of a URL, the command line tool now respects the MAPBOX_HOST environment variable alongside the MAPBOX_ACCESS_TOKEN environment variable. An access token is scoped to a single API endpoint, so this configuration option makes it possible to run the tool against a proxy or staging server for testing purposes.

RouteOptions(url:) now returns nil if given a Mapbox Map Matching API request URL, and MatchOptions(url:) returns nil if given a Mapbox Directions API request URL. Previously, you could mix and match URLs to convert between RouteOptions and MatchOptions. Now, you’ll need to use JSONEncoder and JSONDecoder as well:

guard let url = URL(string: "https://api.mapbox.com/directions/v5/mapbox/driving-traffic/…"),
    let routeOptions = RouteOptions(url: url),
    let encodedOptions = try? JSONEncoder().encode(self) else { return }
try JSONDecoder().decode(MatchOptions.self, from: encodedOptions)

#564 would unblock a more convenient conversion workflow.

Some tangential changes along the way:

• When the MAPBOX_ACCESS_TOKEN environment variable is unset, the tool exits with an error code instead of crashing.
• When a JSON configuration file path is passed into the tool, any tilde is expanded during validation, fixing an issue where an otherwise valid file path got rejected.
• Removed mentions of the --waypoints and --url options from the command line tool’s documentation that probably came from Convert from Directions API URL to RouteOptions #580.

Fixes #692 and fixes #724. Supersedes #580. Depends on #727.

/cc @mapbox/navigation-ios @purew

[1ec5]

The name of this environment variable is consistent with the Mapbox Python SDK, which similarly reads credentials from the environment. It differs from the MGLMapboxAPIBaseURL Info.plist key that applications would set, but the naming conventions for environment variables are different than for Info.plist keys anyways.

[1ec5]

This is kind of unwieldy as an argument description. A possible future improvement would be to accept multiple configurations, perhaps a mix of files and URLs, and merge them somehow.

[jill-cardamon]

will you document that possible future improvement?

[1ec5]

Let’s track it as tail work in #729.

[1ec5]

This was pretty annoying: Credentials(url:) calls the required initializer Credentials(accessToken:host:). If the URL doesn’t have the access_token query parameter set, then the required initializer gets a nil access token, resulting in a precondition failure:

mapbox-directions-swift/Sources/MapboxDirections/Credentials.swift

Line 56 in 50d0941

precondition(accessToken != nil && !accessToken!.isEmpty, "A Mapbox access token is required. Go to <https://account.mapbox.com/access-tokens/>. In Info.plist, set the MBXAccessToken key to your access token, or use the Directions(accessToken:host:) initializer.")

The code here has no opportunity to fall back to the access token from the environment, so instead it has to proactively fall back inside the URL before initializing the Credentials object.

[1ec5]

This is why DirectionsOptions(url:) has to return nil when given a URL whose path conflicts with the abridgedPath property. If it doesn’t return nil, then either RouteOptions and MatchOptions would be equally likely to initialize based on the same URL, mooting the coalescing operator.

Maybe it would be cleaner to nix the OptionsType generic parameter in favor of an enumeration with associated values that gets passed into this method, since the two APIs aren’t all that different. But I’ll leave it for now in case another API needs this kind of flexibility.