Package Store Events
The C3 AI Package Store communicates with the clients through events and listeners. A client can call Pkg.Store#listen and access the Pkg.Store.ListenResult#eventStream. The EventStream#onNext takes a lambda, the event handler, as the primary way clients receive and process events. These events are defined under Pkg.File.Event.
See also the Pkg.Store Type documentation for additional information.
Fields defined on Pkg.File.Event
sequenceNum
The sequence number is kept by the Pkg.Store and starts at 1. It increases everytime a new event is sent. Because sync and validate steps for Pkg.Store are by default NOT synchronous, the sequence number should not be used for any kind of ordering.
targetFiles
Each event provides some information about a set of Pkg.File(s). Every file is in the form meta://packageName/path/to/file.ext, and may include files that the Pkg.Store generated. For example, meta://packageName/gen/cache/Pkg.Issue/packageName%2Fpath%2Fto%2Ffile.ext.json is a Pkg.Issue JSON for UrlEncoder.encode("packageName/path/to/file.ext").
targetFilesInfo
Pkg.Path of each Pkg.File in targetFiles has a corresponding Pkg.File.Info, stored in the targetFilesInfo map where the Pkg.Path is the key, and the according Pkg.File.Info is the value.
kind
The Pkg.File.Event.Kind enum contains information about a change. The enums defined are ADD, REMOVE, UPDATE, VALIDATE, END, and INFO. See the "Kinds of events" section below for more details.
Pkg.File.Event versus Pkg.Event
Pkg.File.Event and Pkg.Event are two different systems, both interacted with by listening to the events they send. Both systems are independent of one another, and their events take different forms.
See Pkg.Event for more information about the event structure of Pkg.Event.
Kinds of Events
REMOVE
The REMOVE event is sent when a file has been removed. This can be from the user deleting a source file from their workspace, or sent from the server to delete a Pkg.Issue when a user fixes an issue. If the Pkg.Store.WriteSpec specifies skipValidation=true, then no REMOVE events are sent for user-removed files.
UPDATE
The UPDATE event is sent during sync to notify that the contents of a file has changed compared to what the server has in the database. The target files will omit any files not written to the database, or if the Pkg.Store.WriteSpec specifies skipValidation=true. UPDATEs also come from files that the server generates in /gen/cache, and these will always send UPDATE events.
VALIDATE
The VALIDATE event signifies that a file(s) has gone through the validation process. It has been checked for Pkg.Issues, and any gen/cache/Pkg.Error will be written soon, if not already.
The target files for VALIDATE contain either a singular file or all the files of a package, which coincides with the two different ways Pkg.Store conducts validation. If validation is done synchronously, which is not the default behavior, Pkg.Store will validate on a file-by-file basis and send VALIDATE events with singular files.
The default validation behavior is to be asynchronous. If the total number of files being asked to be validated is under a threshold Pkg.Store.Config#maxPathsToValidate, then Pkg.Store will also validate file-by-file.
Otherwise, Pkg.Store next will check the percentage of files for each package being validated. If the percentage of a files for a package is over the Pkg.Store.Config#fullValidationPct, then Pkg.Store will do a full package validation and validate all the files in that package at the same time. The resulting target files of the VALIDATE event will contain all files belonging to the package.
Otherwise, the percentage of the files in the package is under the threshold, and Pkg.Store will perform the previously mentioned file-by-file validation.
The actual validation steps are done using the Pkg API. Pkg.Store just ensures that the dependency chains between packages are respected and dependent packages notified.
END
The END event is sent once during the end of an asynchronous validation call. It echos back the paths that were passed in to be validated.
INFO
The INFO event is sent whenever an error occurs during the validation of a file. Errors in a Pkg.File would usually also be written into a Pkg.Issue in the gen/cache/Pkg.Error directory of a package, but certain types of errors do not fit neatly into this paradigm.
If the file at meta://thisPkgDoesNotExist/src/MyType.c3typ is asked to be validated, Pkg.Store cannot associate MyType.c3typ with a package. Currently, this is handled by sending an INFO event without writing a Pkg.Issue file.
On the other hand, errors can be thrown where it cannot be tracked to a corresponding file. The Pkg API will create a Pkg.Issue defaulted to the current package and {packageName}.c3pkg.json as the Pkg.Path. No INFO events are be sent in this case.
There is not a one-to-one mapping between INFO events and Pkg.Issue.