package coolbeans.api.v1
Get desktop application:
View/edit binary Protocol Buffers messages
service Cluster
cluster.proto:10Service provides functionality to work with the cluster
rpc IsNodeLeader (, )
cluster.proto:25IsNodeLeader, Check if this current node is a leader
message
cluster.proto:45bool is_leader = 1
is_leader is a boolean value indicating if this current node is a leader or not
rpc Join (, )
cluster.proto:16Join, allows a calling node to make a request to join this cluster. It is required that the node that this is called into is a leader node. Refer: the specific implementation for error codes
message
cluster.proto:32string node_id = 1
Node ID of the node interested in joining
string addr = 2
Address of the replica interested in joining
rpc Leave (, )
cluster.proto:22Leave, allows a calling node to leave the cluster. It is required that the node that this is called into is a leader node. Refer: the specific implementation for error codes
message
cluster.proto:40string node_id = 1
Node ID of the node requested to leave
rpc Snapshot (, )
cluster.proto:29Snaoshot, requests the server to return a user defined snapshot of the specific node.
service JobStateMachine
jsm.proto:11rpc Bury (, )
jsm.proto:38Bury this job, if this job is in the reserved state
message
jsm.proto:244int64 job_id = 1
The job identifier of the job to be buried
uint32 priority = 2
Refer Job.priority, the new priority for the job
string client_id = 3
Client id of the request
string proxy_id = 4
proxy_id is the id of the proxy server that forwarded this request
rpc CheckClientState (, )
jsm.proto:29CheckClientState queries the job state machine whether the provided list of clientIds are waiting for reservations.
message
jsm.proto:208string proxy_id = 1
proxy_id is the id of the proxy server that forwarded this request
repeated string client_ids = 2
Array of all client_ids
message
jsm.proto:217string proxy_id = 1
proxy_id is the id of the proxy server that forwarded this request
repeated string waiting_client_ids = 2
Array of all client_ids waiting for reservations
repeated string not_waiting_client_ids = 3
Array of all client_ids not waiting for reservations
repeated string missing_client_ids = 4
Array of all client_ids unknown or missing on the server
rpc Delete (, )
jsm.proto:18Delete a job with the provided job id
message
jsm.proto:96int64 job_id = 1
The job identifier of the job to be deleted
string proxy_id = 2
the proxy identifier forwarding the client's request
string client_id = 3
the client identifier of the client (deleting this job)
rpc GetJob (, )
jsm.proto:47Peek a specific job (by the JobID)
message
jsm.proto:276int64 job_id = 1
Id of the job to get
message
jsm.proto:281optional job = 1
An optional job if set.
rpc GetStatsJobYaml (, )
jsm.proto:59Retrieve a job statistics
message
jsm.proto:296int64 job_id = 1
Id of the job to get
message
jsm.proto:301bytes stats_yaml = 1
Yaml representation stats (key-value pairs)
rpc GetStatsTubeYaml (, )
jsm.proto:62Retrieve a tube's statistics
message
jsm.proto:306string tube_name = 1
name of the tube
message
jsm.proto:311bytes stats_yaml = 1
Yaml representation stats (key-value pairs)
rpc GetStatsYaml (, )
jsm.proto:65Retrieve overall statistics
message
jsm.proto:316bytes stats_yaml = 1
Yaml representation stats (key-value pairs)
rpc Kick (, )
jsm.proto:41Kick this job, if this job is in a buried stated to ready state
message
jsm.proto:258int64 job_id = 1
The job identifier of the job to be Kicked
rpc KickN (, )
jsm.proto:44Kick at-most n jobs in this tube,
message
jsm.proto:263string tube_name = 1
Refer Job.tube_name
int32 bound = 2
bound is the maximum number of jobs to kick
message
jsm.proto:271int32 jobs_kicked = 1
The actual number of jobs kicked
rpc ListTubes (, )
jsm.proto:68Retreive a list of all Tubes
message
jsm.proto:321repeated string tubes = 1
rpc PeekBuried (, )
jsm.proto:50Peek a tube's buried jobs
rpc PeekDelayed (, )
jsm.proto:53Peek a tube's delayed jobs
rpc PeekReady (, )
jsm.proto:56Peek a tube's ready jobs
rpc Put (, )
jsm.proto:15Put creates a new job with the provided job parameters The response contains the identifier of the job created
message
jsm.proto:71uint32 priority = 1
Refer Job.priority
int64 delay = 2
Refer Job.delay
int32 ttr = 3
Refer Job.ttr
string tube_name = 4
Refer Job.tube_na,e
int32 body_size = 5
Refer Job.body_size
bytes body = 6
Refer Job.body
message
jsm.proto:91int64 job_id = 1
The job identifier of the new job created
rpc Release (, )
jsm.proto:32Release a reserved job back to either a Ready or a Delayed state
message
jsm.proto:190int64 job_id = 1
The job identifier of the job to be released
string client_id = 2
The identifier of the client asking for the release
string proxy_id = 3
proxy_id is the id of the proxy server that forwarded this request
int64 delay = 4
A delay if set to a value > 0 marks the job as delayed
uint32 priority = 5
the new priority with which this job is released
rpc Reserve (, )
jsm.proto:21Reserve is a request to reserve a channel for a client by this proxy
message
jsm.proto:107string client_id = 1
client id of the reservation
string request_id = 2
request id identify this reservation
int32 timeout_secs = 3
reservation timeout in seconds
repeated string watched_tubes = 4
array of tubes to watch
string proxy_id = 5
the proxy identifier forwarding the client's request
rpc StreamReserveUpdates (, stream )
jsm.proto:26StreamReserveUpdates is a streaming RPC from the server back to client Reservations are streamed as they are available for this proxy
message
jsm.proto:129string proxy_id = 1
the proxy identifier requesting reservation update
rpc Touch (, )
jsm.proto:35Extend a reserved job's reservation TTL by its TTR (time-to-run)
message
jsm.proto:232int64 job_id = 1
The job identifier of the job to be touched
string client_id = 2
The identifier of the client asking for the release
string proxy_id = 3
proxy_id is the id of the proxy server that forwarded this request
message
jsm.proto:338OpType op = 1
Indicates the type of operation
int64 now_secs = 2
time in seconds from epoch this request is made
bytes body = 3
The operation request body
message
jsm.proto:349ResultCode error_code = 1
error code
string error_message = 2
error message (typically set if error_code > 0
bytes body = 3
The response body
message
client.proto:7Used in:
string client_id = 1
identifier of the client that requested a reservation
int64 resv_deadline_at = 2
reservation deadline at (clock time)
bool is_waiting_for_resv = 3
boolean indicating if the client is waiting for a reservation
int64 tick_at = 4
clock time at which the client needs some processing
string req_id = 5
request id of the current reservation request
int32 heap_index = 6
heap index value for this client reservation
repeated string watched_tube = 7
names of the tubes current watched for resrervations
message
empty.proto:7Used as request type in: Cluster.IsNodeLeader, Cluster.Snapshot, JobStateMachine.GetStatsYaml, JobStateMachine.ListTubes
Used as response type in: Cluster.Join, Cluster.Leave, Cluster.Snapshot, JobStateMachine.Bury, JobStateMachine.Delete, JobStateMachine.Kick, JobStateMachine.Release, JobStateMachine.Touch
(message has no fields)
message
job.proto:16Used in: , ,
int64 id = 1
Unique identifier for job
uint32 priority = 2
Priority is an integer < 2**32. Jobs with smaller priority values will be scheduled before jobs with larger priorities. The most urgent priority is 0; the least urgent priority is 4,294,967,295.
int64 delay = 3
delay is an integer number of seconds to wait before putting the job in the ready queue. The job will be in the "delayed" state during this time. Maximum delay is 2**32-1.
int32 ttr = 4
TTR/time to run -- is an integer number of seconds to allow a worker to run this job. This time is counted from the moment a worker reserves this job. If the worker does not delete, release, or bury the job within <ttr> seconds, the job will time out and the server will release the job. The minimum ttr is 1. If the client sends 0, the server will silently increase the ttr to 1. Maximum ttr is 2**32-1.
string tube_name = 5
tube_name is the name of the tube associated with this job
int64 created_at = 6
created is the time in UTC the job is created
int64 ready_at = 7
ready_at is the time in UTC the job is ready
int64 expires_at = 8
expires_at is the time in UTC, when current reservation expires
JobStateProto state = 9
state is the current state of this job
string reserved_by = 10
reserved_by is the identifier of the client which has reserved this job, the value is empty if un-reserved
int32 body_size = 11
body_size is an integer indicating the size of the job body, not including the trailing "\r\n". This value must be less than max-job-size (default: 2**16)
bytes body = 12
body is the job body -- a sequence of bytes of length BodySize
int64 buried_at = 13
buried_at the clock time when the job is buried
uint32 reserve_count = 14
reserve_count is the number of times this job has been reserved.
uint32 timeout_count = 15
timeoutCount is the number of times this job has timed out during a reservation.
uint32 release_count = 16
release_count is the number of times a client has released this job from a reservation.
uint32 bury_count = 17
bury_count is the number of times this job has been buried.
uint32 kick_count = 18
kick_count is the number of times this job has been kicked
Used in:
INITIAL = 0
READY = 1
RESERVED = 2
BURIED = 3
DELAYED = 4
DELETED = 5
enum OpType
jsm.proto:360Used in:
UNKNOWN = 0
PUT = 1
RESERVE = 2
TICK = 3
DELETE = 4
RELEASE = 5
CHECK_CLIENT_STATE = 6
BURY = 7
KICK = 8
KICKN = 9
TOUCH = 10
GET_JOB = 11
PEEK_READY = 12
PEEK_BURIED = 13
PEEK_DELAYED = 14
STATS_JOB_YAML = 15
STATS_TUBE_YAML = 16
STATS_YAML = 17
LIST_TUBES = 18
message
jsm.proto:286Used as request type in: JobStateMachine.PeekBuried, JobStateMachine.PeekDelayed, JobStateMachine.PeekReady
string tube_name = 1
the name of the tube
message
jsm.proto:291Used as response type in: JobStateMachine.PeekBuried, JobStateMachine.PeekDelayed, JobStateMachine.PeekReady
optional job = 1
An optional job if set.
message
jsm.proto:163Used in: , ,
string request_id = 1
request_id associated with this reservation
string client_id = 2
client id assinged to this reservation
ReservationStatus Status = 3
Result of this reservation
int64 job_id = 4
job id (assigned) if Status is matched
int32 body_size = 5
job body size (assigned) if Status is matched
bytes body = 6
job body (assigned) if Status is matched
string error_msg = 7
error message (assigned) if Status is error
string proxy_id = 8
proxy_id is the id of the proxy server that forwarded this reservation request
Used in:
UnknownRS = 0
Unknown ~~> UnknownRS (yuck!!) Note that enum values use C++ scoping rules, meaning that enum values are siblings of their type, not children of it. Therefore, "Unknown" must be unique within "coolbeans.api.v1", not just within "ResultCode"
Queued = 1
DeadlineSoon = 2
Matched = 3
Timeout = 4
Error = 5
message
jsm.proto:144Used in:
repeated entries = 1
Reservation object encapsulated in this response
message
jsm.proto:124Used as response type in: JobStateMachine.Reserve, JobStateMachine.StreamReserveUpdates
optional reservation = 1
Reservation object encapsulated in this response
message
jsm.proto:134optional reservation = 1
Reservations encapsulated in this response
C & P from GRPC error codes https://github.com/grpc/grpc-go/blob/master/codes/codes.go
Used in:
OK = 0
OK is returned on success.
Canceled = 1
Canceled indicates the operation was canceled (typically by the caller).
Unknown = 2
Unknown error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
InvalidArgument = 3
InvalidArgument indicates client specified an invalid argument. Note that this differs from FailedPrecondition. It indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DeadlineExceeded = 4
DeadlineExceeded means operation expired before completion. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.
NotFound = 5
NotFound means some requested entity (e.g., file or directory) was not found.
AlreadyExists = 6
AlreadyExists means an attempt to create an entity failed because one already exists.
PermissionDenied = 7
PermissionDenied indicates the caller does not have permission to execute the specified operation. It must not be used for rejections caused by exhausting some resource (use ResourceExhausted instead for those errors). It must not be used if the caller cannot be identified (use Unauthenticated instead for those errors).
ResourceExhausted = 8
ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FailedPrecondition = 9
FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation's execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc. A litmus test that may help a service implementor in deciding between FailedPrecondition, Aborted, and Unavailable: (a) Use Unavailable if the client can retry just the failing call. (b) Use Aborted if the client should retry at a higher-level (e.g., restarting a read-modify-write sequence). (c) Use FailedPrecondition if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FailedPrecondition should be returned since the client should not retry unless they have first fixed up the directory by deleting files from it. (d) Use FailedPrecondition if the client performs conditional REST Get/Update/Delete on a resource and the resource on the server does not match the condition. E.g., conflicting read-modify-write on the same resource.
Aborted = 10
Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. See litmus test above for deciding between FailedPrecondition, Aborted, and Unavailable.
OutOfRange = 11
OutOfRange means operation was attempted past the valid range. E.g., seeking or reading past end of file. Unlike InvalidArgument, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate InvalidArgument if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OutOfRange if asked to read from an offset past the current file size. There is a fair bit of overlap between FailedPrecondition and OutOfRange. We recommend using OutOfRange (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OutOfRange error to detect when they are done.
Unimplemented = 12
Unimplemented indicates operation is not implemented or not supported/enabled in this service.
Internal = 13
Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.
Unavailable = 14
Unavailable indicates the service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations. See litmus test above for deciding between FailedPrecondition, Aborted, and Unavailable.
DataLoss = 15
DataLoss indicates unrecoverable data loss or corruption.
Unauthenticated = 16
Unauthenticated indicates the request does not have valid authentication credentials for the operation.
message
jsm.proto:328Encapsulates a snap of the entire system
repeated jobs = 1
Array of all jobs currently in the system
repeated reservations = 2
Arrayy of all client reservation entries in the system
message
jsm.proto:139map<string, > proxy_reservations = 3
Reservations grouped by proxy id