Request for documentation clarification around fn request_document

[issackelly]

Writing an issue I had while integrating, may follow up with a PR as I continue.

If request_document is awaited, does that suggest that the document is fully syncronized at-time-of-return or does it mean that the sync with your repo has been acknowledged or something else?

[issackelly]

This request_document API appears to only pull it in memory if it was pulled from the network without sending the unchanged document to the storage adapter. That was a surprise and maybe we can document it. I think I need to make a change to get .save to be called and therefore to persist locally.

[gterzian]

that the document is fully syncronized at-time-of-return

That is the right answer.

without sending the unchanged document to the storage adapter.

When a document has been successfully requested, it will also be persisted via the storage API. I've added an assertion for this in our test suite, see b8f69d7

Note that this happens concurrently to request_document(..).await returning, so if you were to check your local storage implementation immediately after request_document(..).await, you could find it still empty(hence the loop in the test).

Agree on the need for documentation.

[issackelly]

Thanks! That test matches my experience yesterday. I was exiting my program immediately after request_document was awaited. The contains document request is a little interesting because there's no assertion other than the key existing.

I don't have an obviously-better idea than that, but the first thing that sticks out at me is that maybe a document ID could be the uuid of the first transaction instead of pre-generated. Then you know you at least have the first head in common if you start syncing?

[gterzian]

Then you know you at least have the first head in common if you start syncing?

It's an interesting idea, for now we do not sync a locally created document until it has been edited. See DocState::LocallyCreatedNotEdited in the doc state machine.

[gterzian]

I was exiting my program immediately after request_document was awaited.

And as discussed, this is solved by calling repo_handle.stop before exiting(more docs needed again).