~mil/mobroute

v0.6.0 2 months ago

This release of Mobroute was focused on tooling updates in order to: make
the library & CLI more friendly to end users; and to aide in the initial
general public release (on F-Droid) for Transito, which is Mobroute's
associated mobile app and reference implementation for runtime library
usage. See below for a detailed list of changes.

1. Library: Public Interface Cleanup - Oneshot & Runtime Functions
The public interface for the Mobroute library has been wholesale reworked
with an eye toward external consumer usage. The largest change is that
the library's API now presents both 'oneshot' and 'runtime' function
variants. The defacto reference implementation for usage of Mobroute's
library 'oneshot' functions is Mobroute's CLI located in the source
`cli/` folder. And the defacto reference implementation for Mobroute's
library 'runtime' functions is the Transito mobile application which
pools a single Mobroute runtime (and database connection) for the entire
app usage.

The Runtime library functions (as utilized by Transito), allow a
*single database connection* & runtime to be persisted between multiple
library function calls. The user first creates a MobrouteRuntime (via
RTInitialize) and then the user is able to perform multiple routing
requests using the same runtime and database connection using the RTRoute
function. While RTRoute is currently the only runtime function available
apart from RTInitialize (to initialize the runtime); this pattern of
using a single runtime/database connection sets things architecturally
in a good place for future updates & planned functionality (such as
querying stoptimes, nearby stops, and similar). See the Transito app for
an example of Mobroute library's runtime functions usage. By convention
all runtime library functions are and will be prefixed with 'RT'.

Meanwhile, Oneshot library functions (as utilized by the Mobroute CLI),
offer functions callable in a single (or 'oneshot') request. Unlike the
runtime library functions, no prior setup is needed for oneshot functions
and this has the benefit that the entire request (for routing requests
and similar) is serializable as a single JSON object. The database
connection is opened at the start of the function call and closed upon
returning with oneshot functions. Do note that internally the new oneshot
library functions (OneshotRoute & OneshotMobsql) use the runtime API
under-the-hood and the oneshot API is largely a convenience for end-users
who want to fire off a routing request with a single call and is the
simpler option for integration for one-off use-cases. See the CLI for
an example of Mobroute library's' oneshot function usage. By convention
all oneshot library functions are and will be prefixed with 'Oneshot'.

2. Library: Initial Documentation
Initial documentation for the Mobroute library has been added in the form
of godoc strings and the overall presentation of the documentation has
been improved if you view within godoc, pkg.go.dev, and similar. More
extensive documentation is slated for a later release (see roadmap),
however for basic usage of the new runtime & oneshot library functions,
the initial documentation (and reference implementations of the Mobroute
CLI & Transito app) added in this release should suffice.

3. CLI: Functionality & Documentation
A number of large changes have been made to the Mobroute CLI. Among
these changes are: (1) the CLI has been reworked to use the newly
updated Oneshot Mobroute library functions, (2) the CLI documentation and
functionality for both the route and passthrough Mobsql functionality has
been reworked to be more friendly to endusers wrt. JSON object formatting
and docstrings in -h help messages (3) YAML functionality has been removed
and all requests are expected to be formatted as JSON, (4) Feed IDs are
used directly instead of the old 'filter format' specification which just
added complexity, and finally (5) error handling is vastly improved due
to both code restructuring & the addition of route request validation
(see next section).

4. Routing: Route Request Validations
Validations have been added for route requests by way of utilizing
struct tags via the github.com/go-playground/validator library which has
been added as a dependency. This library allows for validations such
as checking the passed transfer categories, output formats, feed IDs,
tunable walk parameter, and similar simply by struct tag annotation. Both
CLI & library calls for routing are validated upon usage. As a result,
the user can now expect much friendlier & more structured error messages
in the case of failed route request due to invalid route parameters.

5. Routing: Embedding of Route Request in GeoJSON Response
The GeoJSON output formatter has been modified to include the original
route request serialized as a JSON string embedded in the output
route LineString property 'metadata' field. This was done largely for
convenience & debugging in that the http://geojson.lrdu.org service which
provides links for the map view output format now automatically passes
through the 'original request'. This has the benefit that the map URLs
(which are easily shareable) are now much easier to debug & replicate in
that all that is needed to 'recreate' a map URL route is simply to run
the mobroute CLI with the JSON buffer included in the map link as in:
`mobroute route -rp '{}'` wherein `{}` is the JSON request.

6. Tooling: MDBID & Source References Renamed to FeedID
All references to 'MDBID' and 'source' in the codebase have been replaced
with the term 'FeedID'. The previously used MDBID and source terms were
used interchangeably and created ambiguity as to what the difference
between these two terms were. Replacing all references should make it
clearer both from the database & in the Go code what exactly is being
referred to. As well the term 'FeedID' should be more self-explanatory
to end users then either of the former terms. This update matches a
similar naming update for FeedID in Mobsql 0.6.

7. Tooling: Go SQLite Driver Portability / Simplification
Since initial versions of Mobroute, there has been a hard dependency on
the SQLite driver library mattn/go-sqlite3. A feature specific to this
library called 'Go SQlite3 Extensions' has been historically utilized to
call Go code directly from SQLite queries in the core of the routing
API. This provided a good amount of convenience in that haversine
distance, timezone lookup, and similar functionality didn't have to
be directly implemented in SQL. However, in this release the reliance
on all 'Go SQLite3 Extensions' functionality has been deliberately
removed. There are a number of reasons this was done; the primary
driving reason has to do with debugging. Without using these bindings,
all queries executed & printed to the console can be simply replicated
just by dumping the exact query in the sqlite CLI with the parameterized
args. This offers a much better developer UX for debugging for both code &
live debugging scenarios. Additionally, without relying on the Go/SQLite
interop extension pattern specific to this library, Mobroute's SQLite
driver could be very simply be switched out in the future for another
Go SQLite driver. This has benefit in both testing scenarios (e.g. in
the case of a bug with the mattn/go-sqlite3 library) and also opens the
door to potential for future optimization wrt. the choice of which Go
SQLite driver is used.