Protobuf Schema

These are the protobuf definitions for parigot itself and the built in services.

Protocol Documentation

Table of Contents

Top

file/v1/file.proto

CloseRequest

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

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.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

CreateRequest

FieldTypeLabelDescription
pathstring
contentstring

CreateResponse

FieldTypeLabelDescription
pathstring
idprotosupport.v1.IdRaw
truncatedbool

DeleteRequest

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

DeleteResponse

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

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.

FieldTypeLabelDescription
pathstringpath is a path to a directory on the host filesystem that is to be loaded in /app
mount_locationstringwhere this new file will exist in the in-memory filesystem… this path will be cleaned lexically and then joined to /app. Note that it is possible create paths with this parameter that cannot be opened because of restrictions on the path in open.
return_on_failboolreturnOnFail should be set to true if you do NOT want the normal behavior of using panic on error. If this value is set to true, the paths that cause an error on import are return in the TestDataResponse.

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.

FieldTypeLabelDescription
error_pathstringrepeated

OpenRequest

FieldTypeLabelDescription
pathstring

OpenResponse

FieldTypeLabelDescription
pathstring
idprotosupport.v1.IdRaw

ReadRequest

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
bufbytesReads up to len(buf) bytes into buf

ReadResponse

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
num_readint32The number of bytes read (0 <= num_read <= len(buf))

WriteRequest

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
bufbytesWrites len(buf) bytes from buf

WriteResponse

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
num_writeint32The number of bytes written from buf (0 <= num_write <= len(buf))

FileErr

NameNumberDescription
NoError0mandatory
DispatchError1mandatory
UnmarshalError2mandatory
MarshalError3mandatory
InvalidPathError4InvalidPathError indicates that the provided path name is not a valid identifier. Identifiers must be the shortest path name equivalent to the given path, derived through pure lexical processing. Specifically, it should start with specific prefix, and any usage of '.' or '..' in the path is disallowed.
AlreadyInUseError5AlreadyInUseError means that the file is already being used.
NotExistError6NotExistError means that the file does not exist
FileClosedError7FileClosedError means that the status of the file is CLOSED, hence it cannot be accessed by a read or write request.
LargeBufError8
InternalError9InternalError means that there are issues with the file service.

File

Method NameRequest TypeResponse TypeDescription
OpenOpenRequestOpenResponseOpen handles the READ-only operation on a file
CreateCreateRequestCreateResponseCreate handles the WRITE-only operation on a file. It creates or truncates the name file in the path. If the file already exists, it is truncated. If the file does not exist, it is created.
CloseCloseRequestCloseResponseClose changes the status of a file to "close"
LoadTestDataLoadTestDataRequestLoadTestDataResponseLoad does NOT check that the file(s) referred to are reasonable in length, do not contain symlinks, are readable, etc. Don't allow this call in prod.
ReadReadRequestReadResponse
WriteWriteRequestWriteResponse
DeleteDeleteRequestDeleteResponseDelete free a file from memory (datacache) or delete it from the disk

Top

syscall/v1/syscall.proto

BindMethodRequest

FieldTypeLabelDescription
host_idprotosupport.v1.IdRaw
service_idprotosupport.v1.IdRaw
method_namestring
directionMethodDirection

BindMethodResponse

FieldTypeLabelDescription
method_idprotosupport.v1.IdRaw

BlockUntilCallRequest

FieldTypeLabelDescription
can_timeoutbool

BlockUntilCallResponse

FieldTypeLabelDescription
paramgoogle.protobuf.Any
methodprotosupport.v1.IdRaw
callprotosupport.v1.IdRaw
timed_outbool

DispatchRequest

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

FieldTypeLabelDescription
service_idprotosupport.v1.IdRaw
method_idprotosupport.v1.IdRaw
paramgoogle.protobuf.Anyinside is another Request object, but we don't know its type
call_idprotosupport.v1.IdRaw
host_idprotosupport.v1.IdRaw

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.

FieldTypeLabelDescription
call_idprotosupport.v1.IdRaw

ExitRequest

ExitRequest is how you can request for your wasm program to exit. In some cases, this will not terminate the process because there may be other services running in the same process.

FieldTypeLabelDescription
codeint32valid values here are 0…192 and values>192 or <0 will be set to 192

ExitResponse

FieldTypeLabelDescription
codeint32

ExportRequest

FieldTypeLabelDescription
serviceFullyQualifiedServicerepeated
host_idprotosupport.v1.IdRaw

ExportResponse

FullyQualifiedService

FieldTypeLabelDescription
package_pathstring
servicestring

LaunchRequest

FieldTypeLabelDescription
service_idprotosupport.v1.IdRaw

LaunchResponse

LocateRequest

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

FieldTypeLabelDescription
package_namestring
service_namestring
called_byprotosupport.v1.IdRaw

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".

FieldTypeLabelDescription
host_idprotosupport.v1.IdRaw
service_idprotosupport.v1.IdRaw
bindingMethodBindingrepeated

MethodBinding

FieldTypeLabelDescription
method_namestring
method_idprotosupport.v1.IdRaw

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.

FieldTypeLabelDescription
callServiceMethodCallrepeated
timeout_in_millisint32
host_idprotosupport.v1.IdRaw

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.

FieldTypeLabelDescription
timeoutbool
callServiceMethodCall
call_idprotosupport.v1.IdRaw
paramgoogle.protobuf.Any
resolvedResolvedCall

RegisterRequest

Register informs the kernel you are one of the known services that can be accessed. Clients use this so they can participate in the dependency graph for startup order.

FieldTypeLabelDescription
fqsFullyQualifiedService
is_clientbool

RegisterResponse

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
existed_previouslybool

RequireRequest

FieldTypeLabelDescription
destFullyQualifiedServicerepeated
sourceprotosupport.v1.IdRaw

RequireResponse

ResolvedCall

FieldTypeLabelDescription
host_idprotosupport.v1.IdRaw
call_idprotosupport.v1.IdRaw
resultgoogle.protobuf.Any
result_errorint32

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.

FieldTypeLabelDescription
host_idprotosupport.v1.IdRaw
call_idprotosupport.v1.IdRaw
resultgoogle.protobuf.Any
result_errorint32

ReturnValueResponse

ReturnValueResponse is currently empty.

ServiceMethodCall

FieldTypeLabelDescription
service_idprotosupport.v1.IdRaw
method_idprotosupport.v1.IdRaw

KernelErr

NameNumberDescription
NoError0
LocateError1LocateError is return when the kernel cannot find the requested service, given by a package name and service name pair.
UnmarshalFailed2UnmarshalFailed is used to indicate that in unmarshaling a request or result, the protobuf layer returned an error.
IdDispatch3IdDispatch means that a dispatch call failed due to an MethodId or ServiceId was not found.
NamespaceExhausted4NamespaceExhausted is returned when the kernel can no along accept additional packages, services, or methods. This is used primarily to thwart attempts at DOS attacks.
NotFound5NotFound means that a package, service, or method that was requested could not be found.
DataTooLarge6DataTooLarge means that the size of some part of method call was bigger than the buffer allocated to receive it. This could be a problem either on the call side or the return side.
MarshalFailed7Marshal means that a marshal of a protobuf has failed.
CallerUnavailable8CallerUnavailable means that the kernel could not find the original caller that requested the computation for which results have been provided. It is most likely because the caller was killed, exited or timed out.
ServiceAlreadyClosedOrExported9KernelServiceAlreadyClosedOrExported means that some process has already reported the service in question as closed or has already expressed that it is exporting (implementing this service). This is very likely a case where there are two servers that think they are or should be implementing the same service.
ServiceAlreadyRequired10ServiceAlreadyRequired means that this same process has already required the given service.
DependencyCycle11DependencyCycle means that no deterministic startup ordering exists for the set of exports and requires in use. In other words, you must refactor your program so that you do not have a cyle to make it come up cleanly.
NetworkFailed12NetworkFailed means that we successfully connected to the nameserver, but failed during the communication process itself.
NetworkConnectionLost13NetworkConnectionLost means that our internal connection to the remote nameserver was either still working but has lost "sync" in the protocol or the connection has become entirely broken. The kernel will close the connection to remote nameserver and reestablish it after this error.
DataTooSmall14DataTooSmall means that the kernel was speaking some protocol with a remote server, such as a remote nameserver, and data read from the remote said was smaller than the protocol dictated, e.g. it did not contain a checksum after a data block.
KernelConnectionFailed15ConnectionFailed means that the attempt to open a connection to a remote service has failed to connect.
NSRetryFailed16NSRetryFailed means that we tried twice to reach the nameserver with the given request, but both times could not do so.
DecodeError17DecodeError indicates that an attempt to extract a protobuf object from an encoded set of bytes has failed. Typically, this means that the encoder was not called.
ExecError18ExecError means that we received a response from the implenter of a particular service's function and the execution of that function failed.
KernelDependencyFailure19DependencyFailure means that the dependency infrastructure has failed. This is different than when a user creates bad set of depedencies (KernelDependencyCycle). This an internal to the kernel error.
AbortRequest20AbortRequest indicates that the program that receives this error should exit because the nameserver has asked it to do so. This means that some other program has failed to start correctly, so this deployment cannot succeed.
ExitRequested21ExitRequested indicates that the program that receives this error should exit because the nameserver permitted it to do so. This is not really an "error" but rather an indication that the caller who requested the exit may do so immediately.
EncodeError22EncodeError indicates that an attempt encode a protobuf with header and CRC has failed.
ClosedErr23ClosedErr indicates that that object is now closed. This is used as a signal when writing data between the guest and host.
GuestReadFailed24GuestReadFailed indicates that we did not successfully read from guest memory. This is usually caused by the proposed address to read from being out of bounds.
GuestWriteFailed25GuestWriteFailed indicates that we did not successfully write to guest memory. This is usually caused by the proposed address for writing to being out of bounds.
BadId26BadId indicates that you passed the zero value or the empty value of a an id type into a system call. This usually means that you did not properly initialize a protobuf.
NotReady27NotReady that the service that was trying to start was aborted because it returned false from Ready(). Usually this error indicates that the program has no way to continue running.
NotRequired28NotRequired that a service has tried to Locate() another service that that the first service did not Require() previously.
RunTimeout29RunTimeout means that the programs timeout has expired when waiting for all the required dependencies to be fulfilled.
ReadOneTimeout30ReadOneTimeout means that the program was trying to request a service/method pair to invoke, but the request timed out.
BadCallId31BadCallId is returned when trying to match up the results and the call of a function resulting in a promise. It is returned if either there is no such cid registered yet or the cid is already in use.

MethodDirection

NameNumberDescription
METHOD_DIRECTION_UNSPECIFIED0
METHOD_DIRECTION_IN1
METHOD_DIRECTION_OUT2
METHOD_DIRECTION_BOTH3

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.

FieldTypeLabelDescription
queue_namestring

CreateQueueResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

DeleteQueueRequest

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

DeleteQueueResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

LengthRequest

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

LengthResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
lengthint64

LocateRequest

LocateRequest is request to access a given queue.

FieldTypeLabelDescription
queue_namestring

LocateResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

MarkDoneRequest

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
msgprotosupport.v1.IdRawrepeated

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
unmodifiedprotosupport.v1.IdRawrepeated

QueueMsg

QueueMsg represents an object returned by a call to Receive.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
msg_idprotosupport.v1.IdRaw
receive_countint32ReceiveCount is an approximation of the number of times this messages has been delivered before this delivery.
receivedgoogle.protobuf.TimestampReceiveTime is an approximation to the first time the message was received. If the message has never been received before, this will be the zero value.
sendergoogle.protobuf.Anysender may be any type (or nil) at the discretion of sender
sentgoogle.protobuf.Timestampwhen the message was sent
payloadgoogle.protobuf.Anypayload must be a serialized protobuf object

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.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
message_limitint32it is expected that you can process all received messages inside the time limit

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.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
messageQueueMsgrepeated

SendRequest

Send requests enqueues the queue messages provided.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
msgQueueMsgrepeated

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.

FieldTypeLabelDescription
succeedprotosupport.v1.IdRawrepeated
failQueueMsgrepeated
failed_onprotosupport.v1.IdRaw

QueueErr

NameNumberDescription
NoError0mandatory
DispatchError1mandatory
UnmarshalError2mandatory
MarshalError3mandatory
InvalidName4InvalidName means that the given queue name is a not a valid identifier. Identifiers must contain only ascii alphanumeric characters and the symbols ".", ",","_" and "-". The first letter of a queue name must be an alphabetic character.
InternalError5InternalError means that the queue's implementation (not the values) passed to it) is the problem. This is roughly a 500 not a 401. This is usually caused by a problem with the internal database used to store the queue items.
NoPayload6NoPayload is an error that means that an attempt was made to create a message a nil payload. Payloads are mandatory and senders are optional.
NotFound7NotFound means that the Queue name requested could not be found. This the queue equivalent of 404.
AlreadyExists8AlreadyExists means that the Queue name is already in use.
UnmarshalFailed9Unmarshal error means that we could not use the protobuf unmarshal successfully for a payload or sender.

Queue

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

Method NameRequest TypeResponse TypeDescription
CreateQueueCreateQueueRequestCreateQueueResponseCreateQueue creates a new named queue. This is useful primarily in preparing for a deployment, not during normal execution. See LocateQueue to find an already existing queue.
LocateLocateRequestLocateResponseLocate finds the named queue and returns the id.
DeleteQueueDeleteQueueRequestDeleteQueueResponseDeleteQueue deletes a named queue. This request will return a specific error code if the queue does not exist.
ReceiveReceiveRequestReceiveResponseReceive a queued message. Just receiving a message does not imply that it is fully processed. You need to call delete or the message will be redelivered at a future point. Messages are not guaranteed to be received in the order sent. If there are no messages ready, the response will be returned with a nil message.
MarkDoneMarkDoneRequestMarkDoneResponseMark a message as done and delete. This should only be done after the processing is completed. If you are worried about idempotentency in your processing,you will need to keep a record of which message Ids you have processed.
LengthLengthRequestLengthResponseLength returns the approximate number of items in the queue.
SendSendRequestSendResponseSend a message for later delivery.

Top

protosupport/v1/protosupport.proto

IdRaw

FieldTypeLabelDescription
highuint64
lowuint64

File-level Extensions

ExtensionTypeBaseNumberDescription
parigot_errorbool.google.protobuf.EnumOptions543211
host_func_namestring.google.protobuf.MethodOptions543212
error_id_namestring.google.protobuf.ServiceOptions543213

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.

FieldTypeLabelDescription
queue_namestring

CreateQueueResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

DeleteQueueRequest

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

DeleteQueueResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

LengthRequest

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

LengthResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
lengthint64

LocateRequest

LocateRequest is request to access a given queue.

FieldTypeLabelDescription
queue_namestring

LocateResponse

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw

MarkDoneRequest

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
msgprotosupport.v1.IdRawrepeated

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

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
unmodifiedprotosupport.v1.IdRawrepeated

QueueMsg

QueueMsg represents an object returned by a call to Receive.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
msg_idprotosupport.v1.IdRaw
receive_countint32ReceiveCount is an approximation of the number of times this messages has been delivered before this delivery.
receivedgoogle.protobuf.TimestampReceiveTime is an approximation to the first time the message was received. If the message has never been received before, this will be the zero value.
sendergoogle.protobuf.Anysender may be any type (or nil) at the discretion of sender
sentgoogle.protobuf.Timestampwhen the message was sent
payloadgoogle.protobuf.Anypayload must be a serialized protobuf object

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.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
message_limitint32it is expected that you can process all received messages inside the time limit

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.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
messageQueueMsgrepeated

SendRequest

Send requests enqueues the queue messages provided.

FieldTypeLabelDescription
idprotosupport.v1.IdRaw
msgQueueMsgrepeated

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.

FieldTypeLabelDescription
succeedprotosupport.v1.IdRawrepeated
failQueueMsgrepeated
failed_onprotosupport.v1.IdRaw

QueueErr

NameNumberDescription
NoError0mandatory
DispatchError1mandatory
UnmarshalError2mandatory
MarshalError3mandatory
InvalidName4InvalidName means that the given queue name is a not a valid identifier. Identifiers must contain only ascii alphanumeric characters and the symbols ".", ",","_" and "-". The first letter of a queue name must be an alphabetic character.
InternalError5InternalError means that the queue's implementation (not the values) passed to it) is the problem. This is roughly a 500 not a 401. This is usually caused by a problem with the internal database used to store the queue items.
NoPayload6NoPayload is an error that means that an attempt was made to create a message a nil payload. Payloads are mandatory and senders are optional.
NotFound7NotFound means that the Queue name requested could not be found. This the queue equivalent of 404.
AlreadyExists8AlreadyExists means that the Queue name is already in use.
UnmarshalFailed9Unmarshal error means that we could not use the protobuf unmarshal successfully for a payload or sender.

Queue

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

Method NameRequest TypeResponse TypeDescription
CreateQueueCreateQueueRequestCreateQueueResponseCreateQueue creates a new named queue. This is useful primarily in preparing for a deployment, not during normal execution. See LocateQueue to find an already existing queue.
LocateLocateRequestLocateResponseLocate finds the named queue and returns the id.
DeleteQueueDeleteQueueRequestDeleteQueueResponseDeleteQueue deletes a named queue. This request will return a specific error code if the queue does not exist.
ReceiveReceiveRequestReceiveResponseReceive a queued message. Just receiving a message does not imply that it is fully processed. You need to call delete or the message will be redelivered at a future point. Messages are not guaranteed to be received in the order sent. If there are no messages ready, the response will be returned with a nil message.
MarkDoneMarkDoneRequestMarkDoneResponseMark a message as done and delete. This should only be done after the processing is completed. If you are worried about idempotentency in your processing,you will need to keep a record of which message Ids you have processed.
LengthLengthRequestLengthResponseLength returns the approximate number of items in the queue.
SendSendRequestSendResponseSend a message for later delivery.

Top

test/v1/test.proto

AddTestSuiteRequest

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

FieldTypeLabelDescription
suiteSuiteInforepeated
exec_packagestring
exec_servicestring

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.

FieldTypeLabelDescription
succeededAddTestSuiteResponse.SucceededEntryrepeated

AddTestSuiteResponse.SucceededEntry

FieldTypeLabelDescription
keystring
valuebool

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.

FieldTypeLabelDescription
namestring
error_messagestring
error_idprotosupport.v1.IdRaw
successbool

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.

FieldTypeLabelDescription
packagestring
servicestring
namestring

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.

FieldTypeLabelDescription
successbool
skippedbool
packagestring
servicestring
namestring
detailComparisonResultrepeated

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.

FieldTypeLabelDescription
namestring
func_namestring

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.

FieldTypeLabelDescription
filter_suitestring
filter_namestring
parallelbool

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.

FieldTypeLabelDescription
regex_failedboolso common we don't even call it an error
num_testint32

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.

FieldTypeLabelDescription
package_pathstring
servicestring
function_namestringrepeated

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).

FieldTypeLabelDescription
successbool
num_successint32
num_failureint32
num_skipint32
packagestring
servicestring
test_successSuiteReportRequest.TestSuccessEntryrepeated
test_skipSuiteReportRequest.TestSkipEntryrepeated
detailSuiteReportRequest.DetailEntryrepeated

SuiteReportRequest.DetailEntry

FieldTypeLabelDescription
keystring
valueComparisonResult

SuiteReportRequest.TestSkipEntry

FieldTypeLabelDescription
keystring
valuebool

SuiteReportRequest.TestSuccessEntry

FieldTypeLabelDescription
keystring
valuebool

SuiteReportResponse

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

TestErr

Error codes

NameNumberDescription
NoError0mandatory
DispatchError1used by generated code
UnmarshalError2used by generated code
ServiceNotFound3ServiceNotFound means that the service that was supposed to be under test could not be found.
Exec4Exec means that the exec itself (not the thing being execed) has failed.
SendFailed5SendFailed means that the Test code itself could not create the necessary queue entries.
Internal6Internal means that the Test code itself (not the code under test) has had a problem.
RegexpFailed7RegexpFailed means that the regexp provided by the caller did not compile and is not a valid go regexp.
Marshal8Marshal is used to when we cannot marshal arguments into to a protobuf.
Queue9Queue means that the there was internal error with the queue that is used by the Test service.
DynamicLocate10DynamicLocate is returned when we cannot discover the protobuf package and service name pair provided.

MethodCallSuite

Method NameRequest TypeResponse TypeDescription
ExecExecRequestExecResponse
SuiteReportSuiteReportRequestSuiteReportResponse

Test

Method NameRequest TypeResponse TypeDescription
AddTestSuiteAddTestSuiteRequestAddTestSuiteResponseAddTestSuite adds all the elements in the request as suites to the TestService list. If you add a Suite more than once, the function lists are merged–the functions that were already present are retained and the response will show these tests as failures.
StartStartRequestStartResponseStart starts the TestManager running all the known tests, implicitly this includes all suites. If you give a suite filter the entire suite's tests are dropped if the suite name doesn't match the filter. For finer granularity you can supple a name filter which walks all the known tests and discards any test that doesn't match the filter.

UnderTest

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

Method NameRequest TypeResponse TypeDescription
ExecExecRequestExecResponseFor the default test setup, this is the method that dispatches requests from the TestService to the appropriate test function.

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)