Adjust search window dynamically to fit the number of itineraries

[t2gran]

Summary

If the result have too few or too many itineraries we adjust the search-window for the next request to better fit the expected size of the search-window. This is not done for the initial search, but for all searches after that. The search-window will scale down to fit the numOfItineraries asked for, or up to 6 itineraries in the result. When paging from a high frequency

In addition this PR also clean up the Paging functionality and add documentation for this.

fix: Calculate start of search window correct

We need to include an extra minute when we want to include the "first removed itinerary" start time in the search window. The search window is [inclusive, exclusive] so to include a time t at the end the search window need to be [t0 , t+1m].

Issue

There is no issue for this.

Unit tests

New unit tests are added and old updated.

Code style

✅

Documentation

✅ This add design doc for paging

Changelog

✅

[hannesj]

LGTM

[t2gran]

What should be the relation between the user set search time window, min/maxWinTimeMinutes and this automatic search window adjusting? I feel like it might make sense that the search window defined by the user is not respected in the next/previous pages but that should be documented. However, I feel like we should have a clear way to limit the maximum search window that can be achieved through the original time window and the adjustments by the paging logic.

I have addressed most of this in comments/fixes above, but I will try to give a summary here:

• When paging we may change any request parameter, if we do we include it in the cursor and ignore the one in the request. We still ask the client to pass in the original request. We may change this without notifying the clients. So, the question is, if we need to document the details (fields overridden), or just the contract. We do return the searchWindowUsed for debugging purposes, so I have added doc for it - but not for other parameter witch is overridden (dateTime and arriveBy). The token i obfuscated using Base64 - a strong message that you should not use the information in it, but you can inspect it.
• The tuning parameters min/maxWinTimeMinutes in the dynamic should probably be respected for all searches. I use it now to limit the window in the paging requests, but I do not think we use them to limit a request from the client with the searchWindow set. I think we should rename these config parameters as well. There is a bit of duplicated code now in the RaptorSearchWindowCalculator and the PagingFactory. This can probably be cleaned up by creating an interface (Role) in raptor and make RaptorSearchWindowCalculator use the functionality in the internal OTP Model.

[leonardehrenfried]

Beautiful!

[t2gran]

Yes, the Instant is a wrapper around epocSeconds, and getting rid of all the slightly different accessors for dataTime felt good. I see now that I forgot to update that JavaDoc, but I think I will draw the line here - there are 95% technical improvements in this PR...

[t2gran]

I added the possibility to configure the maxJourneyDuration witch we need at Entur. This is default 24H - this is a change from the existing 3 days, so make sure you add this to your configs if you need it!

This files are changed:

• NodeAdapter.java
• NodeAdapterTest.java
• RoutingResponseMapper.java

[leonardehrenfried]

This looks really good. Do you want to add a line to Configuration.md about maxJourneyTime?

[t2gran]

I can do it as a separate PR maybe to get this merged, I do not remember if we document the request parameters.