syscall.proto

syntax = "proto3";
package syscall.v1;
option go_package="g/syscall/v1;syscall";
import "protosupport/v1/protosupport.proto";
import "google/protobuf/any.proto"; 

// The syscall package does not have a "service" because these are
// _function_  calls made against the kernel of parigot.  
// If you made such a kernel service, how would you Locate it without 
// needing a kernel?

// This file defines some error constants for each of the
// built-in (kernel) types.  These are errors that intended to
// be compared against when receiving an error value. The first
// test of the error value is `IsError()` and if that is true
// you can use `ErrorCode()` to get a int32 that is the error
// code.  You can compare it to values in these enums at your
// discretion.  
//
// All of the kernel calls return KernelErr as the error code.
// Error codes can be converted to and from strings with the maps KernelErr_value and KernelErr_name.

enum KernelErr{
    option (protosupport.v1.parigot_error) = true;
    NoError = 0;
    // LocateError is return when the kernel cannot find the requested
    // service, given by a package name and service name pair.
    LocateError = 1;
    // UnmarshalFailed is used to indicate that in unmarshaling
    // a request or result, the protobuf layer returned an error.
    UnmarshalFailed = 2;
    // IdDispatch means that a dispatch call failed due to an
    // MethodId or ServiceId was not found.  This is also used when
	// binding a method if the name is invalid.
    IdDispatch = 3;
    // NamespaceExhausted is returned when the kernel can no
	  // along accept additional packages, services, or methods.  This is used
	  // primarily to thwart attempts at DOS attacks.
	  NamespaceExhausted = 4;
  	// NotFound means that a package, service, or method that was requested
	  // could not be found.
	  NotFound = 5;
  	// DataTooLarge 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.
	  DataTooLarge = 6;
	  // Marshal means that a marshal of a protobuf has failed.  
	  MarshalFailed = 7;
	  // CallerUnavailable 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.
	  CallerUnavailable = 8;
	  // KernelServiceAlreadyClosedOrExported 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.
	  ServiceAlreadyClosedOrExported = 9;
	  // ServiceAlreadyRequired means that this same process has already
	  // required the given service.
	  ServiceAlreadyRequired = 10;
	  // DependencyCycle 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.
	  DependencyCycle = 11;
	  // NetworkFailed means that we successfully connected to the nameserver, but failed
	  // during the communication process itself.
   	 NetworkFailed = 12;
	  // NetworkConnectionLost 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.
	  NetworkConnectionLost = 13;
	  // DataTooSmall 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.
	  DataTooSmall = 14;
	  // ConnectionFailed means that the attempt to open a connection to a remote
	  // service has failed to connect.
	  KernelConnectionFailed = 15;
	  // NSRetryFailed means that we tried twice to reach the nameserver with
	  // the given request, but both times could not do so.
	  NSRetryFailed = 16;
	  // DecodeError 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.
	  DecodeError = 17;
	  // ExecError means that we received a response from the implenter of a particular
	  // service's function and the execution of that function failed.
	  ExecError = 18;
	  // DependencyFailure 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.
	  KernelDependencyFailure = 19;
	  // AbortRequest 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.
	  AbortRequest = 20;
	  // EncodeError indicates that an attempt encode a protobuf
	  // with header and CRC has failed.
	  EncodeError = 22;
	  // ClosedErr indicates that that object is now closed.  This is used
	  // as a signal when writing data between the guest and host.
	  ClosedErr = 23;
	  // GuestReadFailed 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.
	  GuestReadFailed = 24;
	  // GuestWriteFailed 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.
	  GuestWriteFailed = 25;
	// BadId 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.
	  BadId = 26;
	// NotReady 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.
	  NotReady = 27;
	// NotRequired that a service has tried to Locate() another service
	// that that the first service did not Require() previously.
	  NotRequired = 28;
	// RunTimeout means that the programs timeout has expired when waiting
	  // for all the required dependencies to be fulfilled.
	  RunTimeout = 29;
	  // ReadOneTimeout means that the program was trying to request
	  // a service/method pair to invoke, but the request timed out.
	  ReadOneTimeout = 30;
	  // WriteTimeout means that the program was trying to send
	  // a request to another service, but timed out before it could do so.
	  WriteTimeout = 31;
	  // BadCallId 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.
	  BadCallId = 32;
	  // ChannelClosed indicates that one of the internal channels used in
	  // waiting for input has been closed unexpectedly.
	  // is already in use.
	  ChannelClosed = 33;
	  // ExitFailed means that we were tyring to send an orderly shutdown but 
	  // could not reach all the of the hosts that we needed to notify.
	  ExitFailed = 34;

};

// 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.
message MethodBundle {
	protosupport.v1.IdRaw host_id = 1;
	protosupport.v1.IdRaw service_id = 2;
	protosupport.v1.IdRaw method_id = 3;
	protosupport.v1.IdRaw call_id = 4;

}

message MethodBinding {
	string method_name = 1;
	protosupport.v1.IdRaw method_id = 2;
}

// LocateRequest is a read from the kernel of the service id associated with a package, service pair.
message LocateRequest {
    string package_name = 1;
    string service_name = 2;
	// called_by is only needed for true clients. If you are doing a call to
	// locate with a service that you did not and could not have known beforehand
	// you should leave this empty.
    protosupport.v1.IdRaw called_by = 3; 
}

// 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".
message LocateResponse {
	protosupport.v1.IdRaw host_id = 1;
    protosupport.v1.IdRaw service_id = 2;
	repeated MethodBinding binding = 3;
}

// DispatchRequest is a request by a client to invoke a particular method with the parameters provided.
message DispatchRequest {
	MethodBundle bundle = 1;
    google.protobuf.Any  param = 3;  // inside is another Request object, but we don't know its type
}

// 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.
message DispatchResponse {
    protosupport.v1.IdRaw call_id = 1; // reserved for internal use
	protosupport.v1.IdRaw target_host_id = 2; // reserved for internal use
}

// 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.
message ReturnValueRequest{
	MethodBundle bundle = 1;
	google.protobuf.Any result = 2;
	int32 result_error = 3;
}

// ReturnValueResponse is currently empty.
message ReturnValueResponse {
}

message BlockUntilCallRequest{
  bool can_timeout= 1;
}

message BlockUntilCallResponse{
  google.protobuf.Any param = 1;
  protosupport.v1.IdRaw method = 2;
  protosupport.v1.IdRaw call = 3;
  bool timed_out = 4;
}

enum MethodDirection {
  METHOD_DIRECTION_UNSPECIFIED = 0;
  METHOD_DIRECTION_IN = 1;
  METHOD_DIRECTION_OUT = 2;
  METHOD_DIRECTION_BOTH = 3;
}

// 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.
message BindMethodRequest  {
  protosupport.v1.IdRaw host_id = 1;
  protosupport.v1.IdRaw service_id = 2;
  string method_name = 3;
  MethodDirection direction = 4;
}

// BindMethodResponse is the method_id of the service and method name provided
// in the request.
message BindMethodResponse {
  protosupport.v1.IdRaw method_id = 1;
}

// 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.
message FullyQualifiedService {
  string package_path = 1;
  string service = 2;
}

// 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.
message ExportRequest {
	protosupport.v1.IdRaw service_id = 1;
	repeated FullyQualifiedService service = 2;
	protosupport.v1.IdRaw host_id = 3;
}

// Nothing to return.
message ExportResponse {
}

// 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.
message RequireRequest {
  repeated FullyQualifiedService dest = 1;
  protosupport.v1.IdRaw source = 2;
}

// RequireResponse is currently empty.
message RequireResponse {
}

// 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.
message LaunchRequest {
  protosupport.v1.IdRaw service_id = 1;
  protosupport.v1.IdRaw call_id = 2; // reserved for internal use
  protosupport.v1.IdRaw host_id = 3; // reserved for internal use
  protosupport.v1.IdRaw method_id = 4; // reserved for internal use

}

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

// 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.
message ExitRequest {
  // For the code in the ExitPair, the valid values here are 0...192 and values>192 
  // or <0 will be set to 192. The valid values for the service are a service id 
  // (typically the service making this request) or an zero valued service, indicating
  // that the entire system should be brought down.
  ExitPair pair = 1;
  protosupport.v1.IdRaw call_id = 2; // reserved for internal use
  protosupport.v1.IdRaw host_id = 3; // reserved for internal use
  protosupport.v1.IdRaw method_id = 4; // reserved for internal use
  bool shutdown_all = 5;

}

// ExitResponse will not happen.  The stack will unwind before this 
// message could be received.
message ExitResponse{
	ExitPair pair = 1;
}

// Register informs the kernel you are one of the running services
// and you want a service id.
message RegisterRequest {
    protosupport.v1.IdRaw host_id =1;
	string debug_name = 2;

}

// RegisterResponse indicates if the registering caller has created
// the new service or not.
message RegisterResponse {
    protosupport.v1.IdRaw service_id =1;
	bool existed_previously = 2;
}

// 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.
message HostBinding {
	    protosupport.v1.IdRaw service_id =1;
	    protosupport.v1.IdRaw host_id =2;
}

// 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.
message ServiceByNameRequest {
    FullyQualifiedService fqs=1;
}

// ServiceByNameResponse returns the list, possibly empty,
// that has all the host bindings for the named service.
message ServiceByNameResponse {
    repeated HostBinding binding = 1;
}

// ServiceByIdRequest looks up the given service by
// its string representation.  This is probably only
// useful for passing service objects over the wire.
message ServiceByIdRequest {
    string service_id = 1;
}

// ServiceByIdResponse returns host binding for the
// service or nothing.
message ServiceByIdResponse {
    HostBinding binding = 1;
}

// 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.
message DependencyExistsRequest {
	protosupport.v1.IdRaw source_service_id =1;
	protosupport.v1.IdRaw dest_service_id =2;
	FullyQualifiedService service_name = 3;
}

// DependencyExistsResponse has the exists field set to 
// true if there exists a sequence of dependencies that
// join source and dest (from the request).
message DependencyExistsResponse {
	bool exists = 1;
}

// ServiceMethodCall is the structure that holds "what's been called" in a service.
message ServiceMethodCall {
	protosupport.v1.IdRaw service_id =1;
	protosupport.v1.IdRaw method_id =2;
}

// 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.
message ResolvedCall {
	protosupport.v1.IdRaw host_id = 1;
	protosupport.v1.IdRaw call_id =2;
	protosupport.v1.IdRaw method_id =3;
	google.protobuf.Any result = 4;
	int32 result_error = 5;
}

// 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.
message ReadOneRequest {
	int32 timeout_in_millis = 1;
	protosupport.v1.IdRaw host_id = 2;
}

// 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.  
message ReadOneResponse {
    bool timeout =1;
	MethodBundle bundle = 2;
	google.protobuf.Any param_or_result = 3; 
	int32 result_err = 4;
	ResolvedCall resolved = 5;
    ExitPair exit =6;
}

// 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.
message ExitPair {
	protosupport.v1.IdRaw service_id = 1;
	int32 code  = 2;
}