sapling/eden/fs/service/eden.stream.thrift

include "eden.thrift"
namespace cpp2 facebook.eden

/** This file holds definitions for the streaming flavor of the Eden interface
 * This is only available to cpp2 clients and won't compile for other
 * language/runtimes. */

service StreamingEdenService extends EdenService {
  /** Prototype of the subscription stream for watchman.
   * We'll certainly want to add some filter predicates to this, but I don't
   * want to get hung up on this in this draft of the API.  The caller can
   * subscribe to the stream of file changes and do something with the data as
   * it streams in.
   * The intended usage pattern is for the client to call
   * getCurrentJournalPosition() to get an initial basis, and then pass that
   * value in to subscribe to receive deltas from that point in time.  This is
   * pretty coarse right now because it will propagate all changes through to
   * watchman.  The initial integration can do this and allow watchman to
   * filter locally.  In the longer run we'll want to add a predicate to this
   * so that we reduce the bandwidth needed between eden and watchman.
   */
  stream<FileDelta> subscribe(
    1: string mountPoint,
    2: JournalPosition fromPosition)
}
additional query API for our thrift interface Summary: This diff adds a couple more things to our thrift interface: 1. Introduces JournalPosition 2. Adds methods to query the current JournalPosition and obtain a delta since a given JournalPosition 3. Augments getMaterializedFiles to also return the current JournalPosition 4. Adds a method to evaluate a `glob` against Eden 5. Adds a method using thrift streaming to subscribe to realtime changes Could probably finesse the naming a little bit. The JournalPosition allows reasoning about changes to files that are not part of an Eden snapshot. Internally the journal position is just the SequenceNumber from the journal datastructures, but when we expose it to clients we need to be able to distinguish between a sequence number from the current instance of the eden service and a prior incarnation (eg: if the process has been restarted, and we have no way to recreate the journal we need to be able to indicate this to the client if they ask about changes in that range). For the convenience of the client we also include the `toHash` (the most recent hash from the journal entry) which is likely useful for the `hg` dirstate operations; it is useful to know that the snapshot may have changed since the last query about the dirstate. The `getFileInformation` method returns the instantaneously available `stat()` like information about the requested list of files. Since we simply don't have historical data on how files in the overlay looked (only how they look now), this method does not allow passing in a JournalPosition. When it comes to comparing historical data, we will need to add an API that accepts two snapshot hashes and generates the results from there. This particular method is geared up to understanding the current state of the world; the obvious use case is plugging in the file list from `getFilesChangedSince` into this function to figure out what's what. * Do we want a function that combines `getFilesChangedSince` + `getFileInformation` into a single RPC? Why is there a glob method? It's to support a use-case in the watchman/buck integration. I'm just sketching it out in the thrift interface at this stage. In the future we also need to be able to express how to carry out a tree walk, but that will require some query predicates that I don't want to get hung up on specifying immediately. Why is the streaming stuff in its own thrift file? We can't generate code for it in java or perhaps also python. It's only needed to plumb data into watchman so it's broken out into its own definition. Nothing depends on that file yet, so it's probably not specified quite right. The important thing is how the subscribe method looks: it's essentially the same as the method to query a delta, but it keeps emitting deltas as they are produced. This is another API that will benefit from query predicates when we get around to specifying them. I've added `JournalDelta::fromHash` and `JournalDelta::toHash` to hold the appropriate snapshot ids in the journal entry; this will allow us to indicate when we've checked out a new snapshot, or created a new snapshot. We have no way to populate these yet; I commented on D3762646 about storing the `snapshotID` that we have during `EdenServiceHandler::mountImpl` into either the `EdenMount` or the proposed `RootInode` class. Once we have that we can simply sample it and store it as we generate `JournalDelta`s. Reviewed By: simpkins Differential Revision: D3860804 fbshipit-source-id: 896c24c354e6f58328fb45c24b16915d9e937108 2016-09-19 22:48:12 +03:00			`include "eden.thrift"`
			`namespace cpp2 facebook.eden`

			`/** This file holds definitions for the streaming flavor of the Eden interface`
			`* This is only available to cpp2 clients and won't compile for other`
			`* language/runtimes. */`

			`service StreamingEdenService extends EdenService {`
			`/** Prototype of the subscription stream for watchman.`
			`* We'll certainly want to add some filter predicates to this, but I don't`
			`* want to get hung up on this in this draft of the API. The caller can`
			`* subscribe to the stream of file changes and do something with the data as`
			`* it streams in.`
			`* The intended usage pattern is for the client to call`
			`* getCurrentJournalPosition() to get an initial basis, and then pass that`
			`* value in to subscribe to receive deltas from that point in time. This is`
			`* pretty coarse right now because it will propagate all changes through to`
			`* watchman. The initial integration can do this and allow watchman to`
			`* filter locally. In the longer run we'll want to add a predicate to this`
			`* so that we reduce the bandwidth needed between eden and watchman.`
			`*/`
			`stream<FileDelta> subscribe(`
			`1: string mountPoint,`
			`2: JournalPosition fromPosition)`
			`}`