Protobuf Schema

Protocol Documentation

Table of Contents

• file/v1/file.proto

  • CloseRequest

  • CloseResponse

  • CreateRequest

  • CreateResponse

  • DeleteRequest

  • DeleteResponse

  • FileInfo

  • LoadTestDataRequest

  • LoadTestDataResponse

  • OpenRequest

  • OpenResponse

  • ReadRequest

  • ReadResponse

  • StatRequest

  • StatResponse

  • WriteRequest

  • WriteResponse

  • FileErr

  • File

• syscall/v1/syscall.proto

  • BindMethodRequest

  • BindMethodResponse

  • BlockUntilCallRequest

  • BlockUntilCallResponse

  • DependencyExistsRequest

  • DependencyExistsResponse

  • DispatchRequest

  • DispatchResponse

  • ExitPair

  • ExitRequest

  • ExitResponse

  • ExportRequest

  • ExportResponse

  • FullyQualifiedService

  • HostBinding

  • LaunchRequest

  • LaunchResponse

  • LocateRequest

  • LocateResponse

  • MethodBinding

  • MethodBundle

  • ReadOneRequest

  • ReadOneResponse

  • RegisterRequest

  • RegisterResponse

  • RequireRequest

  • RequireResponse

  • ResolvedCall

  • ReturnValueRequest

  • ReturnValueResponse

  • ServiceByIdRequest

  • ServiceByIdResponse

  • ServiceByNameRequest

  • ServiceByNameResponse

  • ServiceMethodCall

  • KernelErr

  • MethodDirection

• queue/v1/queue.proto

  • CreateQueueRequest

  • CreateQueueResponse

  • DeleteQueueRequest

  • DeleteQueueResponse

  • LengthRequest

  • LengthResponse

  • LocateRequest

  • LocateResponse

  • MarkDoneRequest

  • MarkDoneResponse

  • QueueMsg

  • ReceiveRequest

  • ReceiveResponse

  • SendRequest

  • SendResponse

  • QueueErr

  • Queue

• protosupport/v1/protosupport.proto

  • IdRaw

  • File-level Extensions

  • File-level Extensions

  • File-level Extensions

  • File-level Extensions

  • File-level Extensions

• queue/v1/queue.proto

  • CreateQueueRequest

  • CreateQueueResponse

  • DeleteQueueRequest

  • DeleteQueueResponse

  • LengthRequest

  • LengthResponse

  • LocateRequest

  • LocateResponse

  • MarkDoneRequest

  • MarkDoneResponse

  • QueueMsg

  • ReceiveRequest

  • ReceiveResponse

  • SendRequest

  • SendResponse

  • QueueErr

  • Queue

• test/v1/test.proto

  • AddTestSuiteRequest

  • AddTestSuiteResponse

  • AddTestSuiteResponse.SucceededEntry

  • ComparisonResult

  • ExecRequest

  • ExecResponse

  • QueuePayload

  • StartRequest

  • StartResponse

  • SuiteInfo

  • SuiteReportRequest

  • SuiteReportRequest.DetailEntry

  • SuiteReportRequest.TestSkipEntry

  • SuiteReportRequest.TestSuccessEntry

  • SuiteReportResponse

  • TestErr

  • MethodCallSuite

  • Test

  • UnderTest

• Scalar Value Types

Top

file/v1/file.proto

CloseRequest

CloseResponse

CloseResponse is not empty because it can return an error. However, there is no action that the receiver of this response can take other than perhaps issuing a warning to the system operators.

CreateRequest

CreateResponse

DeleteRequest

DeleteResponse

FileInfo

Define the FileInfo struct

LoadTestDataRequest

LoadTestDataRequest loads the contents of given directory from the host file system into the /app directory of the test filesystem (in memory). This is only intended to be use for test code.

LoadTestDataResponse

LoadTestDataResponse contains a list of paths that caused an error during loading. This value is only returned if the LoadRequest has the returnOnFail set to true. If LoadDataRequest.return_on_fail is false since by definition the error_path will be empty.

OpenRequest

OpenResponse

ReadRequest

ReadResponse

StatRequest

StatRequest asks for the information about a file

StatResponse

Use the FileInfo struct in the StatResponse message

WriteRequest

WriteResponse

FileErr

Invalid example:

'/parigot/app/..' -> '..' is not allowed 	'/parigot/app/./' -> '.' is not allowed 	'/parigot/app/foo\bar' -> '\' is not allowed 	'//parigot/app/foo', '/parigot/app' -> prefix should be '/parigot/app/' |

| AlreadyInUseError | 5 | File status related errors

The file is already being used. | | NotExistError | 6 | The file/path does not exist | | FileClosedError | 7 | The file status is CLOSED, cannot be accessed by a read or write request | | EOFError | 8 | The file is at the end of the file | | ReadError | 9 | Some error happened during reading a file | | WriteError | 10 | Some error happened during writing a file | | OpenError | 11 | Some error happened during opening a file | | DeleteError | 12 | Some error happened during deleting a file | | CreateError | 13 | Some error happened during creating a file | | NoDataFoundError | 14 | No data file found in the directory | | LargeBufError | 15 | The buffer for the file is too large | | InternalError | 16 | There are internal issues with the file service |

File

Top

syscall/v1/syscall.proto

BindMethodRequest

BindMethodRequest is used to tell parigot that the given service_id (located at host_id) has an implementation for the given method name. This will create the mapping to a method_id, which is in the response. The direction parameter is either METHOD_DIRECTION_IN, OUT, or BOTH. IN means thath the method has no output parameter (the result is ignored), OUT means the method has no input parameters, and BOTH means that both input and output parameters are used.

BindMethodResponse

BindMethodResponse is the method_id of the service and method name provided in the request.

BlockUntilCallRequest

BlockUntilCallResponse

DependencyExistsRequest

DependencyExistsRequest is used to check if there a dependency path from source to destination. Callers should use either a target service or a target service name, not both. The semantics are slightly different. When you ask about the name of a service, it is a question about what the service has declared with require calls. When you ask about a specific service you are asking if a dependency path between the two services exists and thus the dest service must be started before the source.

DependencyExistsResponse

DependencyExistsResponse has the exists field set to true if there exists a sequence of dependencies that join source and dest (from the request).

DispatchRequest

DispatchRequest is a request by a client to invoke a particular method with the parameters provided.

DispatchResponse

DispatchResponse sent by the server back to a client. This what is returned as the intermediate value to the caller, because the caller cannot block. This call_id value can be used on the client side to map to additional info about the call.

ExitPair

ExitPair is a structure that is a service that is requesting an exit and the exit code desired. The service can be empty if the caller wants the entire suite of services to be exited. Code will be in the "allowed" range of 0 to 192.

ExitRequest

ExitRequest is how you can request for your wasm program, or the whole system to exit. This will not terminate the process immediately as there may be other services running that need to be notified.

ExitResponse

ExitResponse will not happen. The stack will unwind before this message could be received.

ExportRequest

ExportRequest informs the kernel that the given service id implements the named services on the host given. Note that the services provided must be distinct.

ExportResponse

Nothing to return.

FullyQualifiedService

FullyQualified service is the complete (protobuf) name of a service as a a string. This is typically something like "foo.v1" for the package and the service name is "Foo". These are the names used by the export, require, and locate calls.

HostBinding

HostBinding is the mapping between a service and a host. Note that a given host may be bound to many services, but a single service is always bound to exactly one host.

LaunchRequest

LaunchRequest is used to block a service until its depnedencies are ready. It returns a future to the guest that can be used to take action once launch is completed.

LaunchResponse

LaunchResponse has nothing in it because the action will be handled by a future created as a result of LaunchRequest.

LocateRequest

LocateRequest is a read from the kernel of the service id associated with a package, service pair.

LocateResponse

LocateResponse hands back the service Id of the package_name and service_name supplied in the request. A service id can be thought of as a (network hostname,port) pair that defines which service's "location".

MethodBinding

MethodBundle

MessageBundle tells the receiver all the necessary info to make a call on a method. Note that when this is sent to a particular server, the HostId is the host id of the caller not the place where the service is implemented.

ReadOneRequest

ReadOneRequest gives a set of service/method pairs that should be considered for a read. The ReadOne operation returns a single service/method pair that has received a call. If the timeout expires, only the timeout bool is returned. If the timeout value is 0, then an instanteous sample is returned. If the timeout value is negative, it means wait forever. In addition to potential calls on the service who requests this read, it is also possible that the return value represents a completed call from a previous point in the execution of the calling program.

ReadOneResponse

ReadOneResponse is returned when the control is turned over to parigot for a period of time via a call to ReadOne. ReadOneResponse returns timeout = true if a timeout has occurred. If timeout is true, all the other fields should be ignored. There are two types of results and these are mutually exclusive.

If resolved is not nil, then this a notification that a call made by this program have completed. The resolved field holds information about the completed call, and that data needs to be matched with the appropriate call ids and the promises resolved.

If resolved is nil, then the call is a call on a service and method exposed by this server.
In that case the pair indicates the method and service being invoked, and the param and call id should be to create a matching ReturnValueRequest.

Note that if the method denoted by the pair does not take input, the value of param should be ignored and it may be nil.

RegisterRequest

Register informs the kernel you are one of the running services and you want a service id.

RegisterResponse

RegisterResponse indicates if the registering caller has created the new service or not.

RequireRequest

Require establishes that the source given is going to import the service given by dest. It is not required that the source locate the dest, although if one does call locate, a check is done to insure require was called previously. This check is done to prevent a common programming mistake.

RequireResponse

RequireResponse is currently empty.

ResolvedCall

ResolvedCall is used to hold the output of a service/method call while we are waiting for the future to be resolved. Note that the host_id here is the host id of the SENDER of this message, so the place that the result was calculated.

ReturnValueRequest

ReturnValueRequest is used to return the result of a function back to the caller. It is the result information of a call to a service/method function.

ReturnValueResponse

ReturnValueResponse is currently empty.

ServiceByIdRequest

ServiceByIdRequest looks up the given service by its string representation. This is probably only useful for passing service objects over the wire.

ServiceByIdResponse

ServiceByIdResponse returns host binding for the service or nothing.

ServiceByNameRequest

ServiceByName looks up the given service and returns all the host bindings associated with it. This does change the internal data structures, only reports on them.

ServiceByNameResponse

ServiceByNameResponse returns the list, possibly empty, that has all the host bindings for the named service.

ServiceMethodCall

ServiceMethodCall is the structure that holds "what's been called" in a service.

KernelErr

MethodDirection

Top

queue/v1/queue.proto

CreateQueueRequest

Create creates a queue or returns an error. Note that this is usually used only once to set up the operating environment.

CreateQueueResponse

CreateQueueResponse returns the queue just created. Errors are passed back out of band.

DeleteQueueRequest

Delete queue deletes a queue and returns the queue id deleted, or sends an error out of band.

DeleteQueueResponse

DeleteQueueResponse returns the (now invalid) queue id of what was just deleted.

LengthRequest

Length requests and approximation of the number of elements in the queue

LengthResponse

LengthResponse returns the queue id identifying the queue we computed the length for.

LocateRequest

LocateRequest is request to access a given queue.

LocateResponse

LocateResponse returns the queue id corresponding to the name provided. It returns errors out of band.

MarkDoneRequest

MarkDone request indicates that the caller has finished processing each message in

MarkDoneResponse

MarkDone returns the list of unmodified (not marked done) messages remaining. In the normal case, this will be empty. If there was an error trying to mark items as done, it returns the error and puts the unmarked elements in the list unmodified

QueueMsg

QueueMsg represents an object returned by a call to Receive.

ReceiveRequest

Receive pulls the available messages from the queue and returns them. Note that if multiple copies of the caller exist, the caller must be prepared to receive the same message multiple times.

1 is usually the right choice here |

ReceiveResponse

Receive response hands the caller a list of messages to process. If you need to return an error, do so out of band.

SendRequest

Send requests enqueues the queue messages provided.

SendResponse

If the queue msg id is an error then we are using the error_detail_msg to return the value. Note that the message id you provide here will changed once we send you the success notification using your id.

QueueErr

Queue

Queue supports a reliable source of messages. Messages may be delivered out of order or delivered multiple times.

Top

protosupport/v1/protosupport.proto

IdRaw

File-level Extensions

Top

queue/v1/queue.proto

CreateQueueRequest

Create creates a queue or returns an error. Note that this is usually used only once to set up the operating environment.

CreateQueueResponse

CreateQueueResponse returns the queue just created. Errors are passed back out of band.

DeleteQueueRequest

Delete queue deletes a queue and returns the queue id deleted, or sends an error out of band.

DeleteQueueResponse

DeleteQueueResponse returns the (now invalid) queue id of what was just deleted.

LengthRequest

Length requests and approximation of the number of elements in the queue

LengthResponse

LengthResponse returns the queue id identifying the queue we computed the length for.

LocateRequest

LocateRequest is request to access a given queue.

LocateResponse

LocateResponse returns the queue id corresponding to the name provided. It returns errors out of band.

MarkDoneRequest

MarkDone request indicates that the caller has finished processing each message in

MarkDoneResponse

MarkDone returns the list of unmodified (not marked done) messages remaining. In the normal case, this will be empty. If there was an error trying to mark items as done, it returns the error and puts the unmarked elements in the list unmodified

QueueMsg

QueueMsg represents an object returned by a call to Receive.

ReceiveRequest

Receive pulls the available messages from the queue and returns them. Note that if multiple copies of the caller exist, the caller must be prepared to receive the same message multiple times.

1 is usually the right choice here |

ReceiveResponse

Receive response hands the caller a list of messages to process. If you need to return an error, do so out of band.

SendRequest

Send requests enqueues the queue messages provided.

SendResponse

If the queue msg id is an error then we are using the error_detail_msg to return the value. Note that the message id you provide here will changed once we send you the success notification using your id.

QueueErr

Queue

Queue supports a reliable source of messages. Messages may be delivered out of order or delivered multiple times.

Top

test/v1/test.proto

AddTestSuiteRequest

AddTestSuiteRequest adds one or more test suites to the list of available suites for the TestService.

AddTestSuiteResponse

AddTestSuiteResponse contains a map that takes a tuple, written as pkg.service.name, and maps it to a boolean to indicate if the given tuple was added successfully.

AddTestSuiteResponse.SucceededEntry

ComparisonResult

Comparison result describes a single comparison that was done during a test. This result is generally optional inside a ExecResult. The name field is not the package, service, or function name, it is a name that can used to narrow down to a single comparison. name can be "", as can error_message. The error_id can be nil. These can be zero value because they are not crucial to the display of the results, although it is highly recommended that if the success == false, then one of error_message or error_id is set.

ExecRequest

ExecRequest is the type that flows from the TestService to the package.service.func that is under test. The package, service, and name are in the request message because the callee might be doing trickery with names (see the map field in the SuiteInfo) and thus needs to know what to emulate, dispatch, etc.

ExecResponse

ExecResponse is what an object under test sends back to the TestService describing the test outcome. A single package/service/name can have many comparisons.

QueuePayload

QueuePayload is the payload that is sent to the TestService via sending and receiving items from the queue. Note that the TestSends these messages during setup and retreives them in the background once the tests have started.

StartRequest

StartRequest is what the client should use to start the tests running. The provided data is exclusive, if filter_suite is provided filter_name may not be, and vice versa. Both the suite and name filters may be empty to request running all tests. filter_name and filter_suite must be legal golang regular expressions. Parallel is currently ignored.

StartResponse

StartResponse returns the number of tests that will be run, given the filters provided in StartRequest. If regex_failed means that one of the regex fields (filter_suite or filter_name) was not a valid golang regex.

SuiteInfo

SuiteInfo is used to describe the set of test functions that a suite has. The map provided goes from the logical name of the test ("MyFunc") to the function the test service will actually request ("MyTrickyDispatcher"). The key and value can be identical in the simple case.

SuiteReportRequest

SuiteReportRequest is passed to the suite from the TestService and contains overall information about the suite's tests. The maps have a key that is the logical function name (the key in the map of SuiteRequest).

SuiteReportRequest.DetailEntry

SuiteReportRequest.TestSkipEntry

SuiteReportRequest.TestSuccessEntry

SuiteReportResponse

SuiteReportResponse is empty because there is nothing valuable that can be sent from the suite to the TestService.

TestErr

Error codes

MethodCallSuite

Test

UnderTest

UnderTest is the service that services should implement to be "under test" and testable via Test.

Scalar Value Types