Add a "play to time" feature to the HistoricalModel API

[mmacfadden]

Versions

• Convergence Version: 1.0.0-rc.9

Description
Presently, you can only play to a version in the HistoricalModel class. It would be helpful to be able to play back the model to a certain point in time. However, it is possible that a version does not explicitly correspond to a particular wall time. Assume the following operations timestamps (all on the same day):

1. Op1: 1:00pm
2. Op2: 1:05pm
3. Op3: 1:07pm

Requesting to play to any time before 1pm or after 1:07pm would be an error condition. Users of the model do know time bounds of the model, so we will expect them to use those as proper bounds. Asking to play back to 1:05pm would bring us to the document with operations 1 and 2 applied. If a valid time (within the min / max bounds) is requested, but that does not correspond to an operation timestamp. The model will be played back to the previous operation. For example if 1:02pm was requested, the model would be at the document version that only has Op1 applied.

Here is the proposed API:

public playToTime(time: Date): Promise<void>;

The following protocol messages will be added:

message GetVersionAtTimeRequestMessage {
  option (scalapb.message).extends = "com.convergencelabs.convergence.proto.RequestMessage";
  option (scalapb.message).extends = "com.convergencelabs.convergence.proto.HistoricalModelMessage";
  option (scalapb.message).extends = "com.convergencelabs.convergence.proto.ClientMessage";

  string modelId = 1;
  google.protobuf.Timestamp targetTime = 2;
}

message GetVersionAtTimeResponseMessage {
  option (scalapb.message).extends = "com.convergencelabs.convergence.proto.ResponseMessage";
  option (scalapb.message).extends = "com.convergencelabs.convergence.proto.HistoricalModelMessage";
  option (scalapb.message).extends = "com.convergencelabs.convergence.proto.ServerMessage";

  int64 versionAtTime = 1;
}

message ConvergenceMessage {

  ...

  oneof body {
    
    ...

    model.GetVersionAtTimeRequestMessage modelGetVersionAtTimeRequest = 143;
    model.GetVersionAtTimeResponseMessage modelGetVersionAtTimeResponse = 144;

    ...

[toebes]

If I create the model at 10am and the first time that anyone modifies the model is 3pm, then I would expect that doing a playto 2:49pm would bring me to the initial version of the model.

Attempting to play to before the model was created is ok to be an error and that should be the only error.

Even if you attempt to play to before the model was created, despite the thrown error, it should be at the first version of the model.

As for going beyond the end of the model, any attempt to jump to any time past the last modified time of the model should go to the last version of the model.

[mmacfadden]

Ok. I agree that handling any time after the model was created is a reasonable request. I do not want to handle the case of before the model. When you open the historical model, it tells you what the minimum valid time is. There is not really a good reason to ask for a time before that, in my opinion. this is something the developer can easily check for or enforce themselves if they want that behavior.

[toebes]

I agree.

[mmacfadden]

This has been implemented.