Protocol Documentation

Table of Contents

github.com/tinyci/ci-agents/ci-gen/grpc/services/asset/server.proto

Top

LogChunk

Receive type

FieldTypeLabelDescription
Chunk bytes

Log binary chunk; typically between 64 and 256 bytes per payload.

LogSend

Sending type

FieldTypeLabelDescription
ID int64

ID of *Run*

Chunk bytes

Log binary chunk; typically between 64 and 256 bytes per payload.

Asset

Asset is the underlying layer for the assetsvc, which manages CI logs and

(soon) other file transfers.

Method NameRequest TypeResponse TypeDescription
PutLog .LogSend stream .google.protobuf.Empty

PutLog sends a log

GetLog .types.IntID .LogChunk stream

GetLog retrieves a log.

github.com/tinyci/ci-agents/ci-gen/grpc/services/data/server.proto

Top

Capabilities

FieldTypeLabelDescription
capabilities string repeated

list of capabilities

CapabilityRequest

FieldTypeLabelDescription
id int64

User ID

capability string

name of capability (See model/user.go)

Count

FieldTypeLabelDescription
count int64

GithubJSON

FieldTypeLabelDescription
JSON bytes

Username string

AutoCreated bool

ListSubscribedTasksRequest

FieldTypeLabelDescription
id int64

User ID

page int64

perPage int64

Name

FieldTypeLabelDescription
name string

NameSearch

FieldTypeLabelDescription
name string

search string

OAuthState

FieldTypeLabelDescription
state string

scopes string repeated

QueueList

FieldTypeLabelDescription
items types.QueueItem repeated

QueueListRequest

FieldTypeLabelDescription
name string

Repository name in owner/repo format

page int64

perPage int64

RefPair

FieldTypeLabelDescription
repoName string

these are in owner/repo format

sha string

RepoRef

FieldTypeLabelDescription
repository int64

refName string

RepoUserSelection

FieldTypeLabelDescription
username string

repoName string

these are in owner/repo format

RunListRequest

FieldTypeLabelDescription
repository string

Parent or Fork

sha string

page int64

perPage int64

RunsForTaskRequest

FieldTypeLabelDescription
id int64

Task ID

page int64

perPage int64

Search

FieldTypeLabelDescription
search string

TaskListRequest

FieldTypeLabelDescription
repository string

Parent or Fork

sha string

page int64

perPage int64

Data

datasvc is the conduit between the other services and the database. Most of

these calls map either directly or close to the model calls.

Method NameRequest TypeResponse TypeDescription
GetErrors Name .types.UserErrors

Retrieve User Error

AddError .types.UserError .google.protobuf.Empty

Add A User Error

DeleteError .types.UserError .google.protobuf.Empty

Delete A User Error

OAuthRegisterState OAuthState .google.protobuf.Empty

Register state with the database.

OAuthValidateState OAuthState OAuthState

Validate returned state within the database.

QueueCount .google.protobuf.Empty Count

QueueCount is the count of the queue

QueueCountForRepository Name Count

QueueCountForRepository counts by repo

QueueListForRepository QueueListRequest QueueList

QueueListForRepository produces a list for the repo of queue items.

QueueAdd QueueList QueueList

QueueAdd adds a new QueueList of items

QueueNext .types.QueueRequest .types.QueueItem

QueueNext retrieves the next item in the queue.

PutStatus .types.Status .google.protobuf.Empty

PutStatus sets the status of the run in the DB.

SetCancel .types.IntID .google.protobuf.Empty

SetCancel cancels a run.

GetCancel .types.IntID .types.Status

GetCancel retrieves the canceled state of the run.

GetRefByNameAndSHA RefPair .types.Ref

Given a name and sha, look up the ref.

PutRef .types.Ref .types.Ref

PutRef saves a ref.

CancelRefByName RepoRef .google.protobuf.Empty

CancelRefByName cancels by branch or tag name.

CancelTask .types.IntID .google.protobuf.Empty

CancelTask cancels the branch by task ID.

EnableRepository RepoUserSelection .google.protobuf.Empty

Enables repository for testing in CI

DisableRepository RepoUserSelection .google.protobuf.Empty

Disables repository for testing in CI

SaveRepositories GithubJSON .google.protobuf.Empty

Given a JSON list of github responses; save all the repos.

PrivateRepositories NameSearch .types.RepositoryList

List all Private Repositories for the user.

OwnedRepositories NameSearch .types.RepositoryList

List all Owned Repositories for the user.

AllRepositories NameSearch .types.RepositoryList

List all repositories for the user.

PublicRepositories Search .types.RepositoryList

List all public repositories.

GetRepository Name .types.Repository

Get a specific repository by name.

RunCount RefPair Count

Count of runs for the given ref pair

RunList RunListRequest .types.RunList

List the runs

GetRun .types.IntID .types.Run

Get a specific Run

GetRunUI .types.IntID .types.Run

Get a specific Run with security details omitted; for UI work.

PutSession .types.Session .google.protobuf.Empty

PutSession saves the session.

LoadSession .types.StringID .types.Session

LoadSession loads the session.

RemoveSubscription RepoUserSelection .google.protobuf.Empty

removes the subscription from the user's account.

AddSubscription RepoUserSelection .google.protobuf.Empty

adds a subscription.

ListSubscriptions NameSearch .types.RepositoryList

lists all the subscriptions for the user.

PutTask .types.Task .types.Task

Add a task to the db.

ListTasks TaskListRequest .types.TaskList

List Tasks

ListSubscribedTasksForUser ListSubscribedTasksRequest .types.TaskList

List tasks only in the user's subscription list.

CountTasks TaskListRequest Count

Count Tasks

CancelTasksByPR .types.CancelPRRequest .google.protobuf.Empty

cancel a task by pull request ID

RunsForTask RunsForTaskRequest .types.RunList

get all runs associated with the task.

CountRunsForTask .types.IntID Count

Count all associated runs with the task.

UserByName Name .types.User

Get a user by name

PatchUser .types.User .google.protobuf.Empty

Update a user -- currently only accepts token changes.

PutUser .types.User .types.User

Create a user

ListUsers .google.protobuf.Empty .types.UserList

List all users.

GetToken Name .types.StringID

Get a auth token (not oauth)

DeleteToken Name .google.protobuf.Empty

Delete the auth token

ValidateToken .types.StringID .types.User

Validate the auth token -- returns the user if successful

GetCapabilities .types.User Capabilities

Retrieves the capabilities for a user

HasCapability CapabilityRequest .types.Bool

Returns true if the user has the capability

AddCapability CapabilityRequest .google.protobuf.Empty

Adds the capability for the user

RemoveCapability CapabilityRequest .google.protobuf.Empty

Removes the capability from the user

github.com/tinyci/ci-agents/ci-gen/grpc/services/log/server.proto

Top

LogMessage

LogMessage is a log message in struct form.

FieldTypeLabelDescription
at google.protobuf.Timestamp

Time of log

level string

Level of log (debug, info, error are supported)

fields google.protobuf.Struct

Fields in map[string]interface{} format

service string

Service name

message string

Message

Log

Log is the logsvc which is responsible for managing log messages.

Method NameRequest TypeResponse TypeDescription
Put LogMessage .google.protobuf.Empty

send a log message to the logsvc.

github.com/tinyci/ci-agents/ci-gen/grpc/services/queue/server.proto

Top

Submission

Submission controls the submission of branches and pull requests. Some

(noted) properties are not externally modifiable, so they will result in a

noop if set.

FieldTypeLabelDescription
parent string

Parent repository

fork string

Fork repository

headsha string

HEAD SHA -- usually the head of the fork

basesha string

Base SHA -- usually the head of the parent

submitted_by string

Who submitted this?

pull_request int64

PullRequest ID if available -- not set during manual submissions

all bool

Test all instead of using diff selection; this is a flag in the UI and can also be triggered by tinycli. It is not used in github hooks except for pushes to master.

manual bool

Flag set if this was a manual submission. Typically managed by the uisvc.

Queue

Queue corresponds to the queuesvc, which is used for managing incoming

results from the hooksvc (github hooks). Runners hit this as well to send

states and get next queue items.

Method NameRequest TypeResponse TypeDescription
PutStatus .types.Status .google.protobuf.Empty

NextQueueItem .types.QueueRequest .types.QueueItem

Submit Submission .google.protobuf.Empty

SetCancel .types.IntID .google.protobuf.Empty

GetCancel .types.IntID .types.Status

github.com/tinyci/ci-agents/ci-gen/grpc/types/bool.proto

Top

Bool

FieldTypeLabelDescription
result bool

result of boolean query

github.com/tinyci/ci-agents/ci-gen/grpc/types/error.proto

Top

Error

Errors that occur within the program's calls after a request. Bound to the

user, not the connection.

FieldTypeLabelDescription
errors string repeated

list of errors that occurred

log bool

whether or not the error is intended to be logged; used internally by some functions.

github.com/tinyci/ci-agents/ci-gen/grpc/types/id.proto

Top

IntID

IntID is a basic integer ID -- it's used to control a variety of things that

use basic sequences and so forth.

FieldTypeLabelDescription
ID int64

ID is the ID.

StringID

StringID is just like types.IntID but instead it's a string!

FieldTypeLabelDescription
ID string

ID is the ID.

github.com/tinyci/ci-agents/ci-gen/grpc/types/queue_item.proto

Top

QueueItem

QueueItems are the subject sent to runners when runners are able to execute

a job. Runners poll for these endless through the queuesvc.

FieldTypeLabelDescription
id int64

ID of queue item

running bool

Is the job running?

runningOn string

What host is it running on

startedAt google.protobuf.Timestamp

When did it start?

queueName string

The name of the queue

run Run

The run itself.

QueueRequest

QueueRequest is issued by runners to the queuesvc.

FieldTypeLabelDescription
queueName string

runningOn string

Status

Status is reported to the queuesvc on completion of a run.

FieldTypeLabelDescription
id int64

status bool

additionalMessage string

github.com/tinyci/ci-agents/ci-gen/grpc/types/ref.proto

Top

Ref

Ref is the encapsulation of a git ref and communicates repository as well as version information.

FieldTypeLabelDescription
id int64

Internal ID of ref

repository Repository

Repository the ref belongs to (typically, the fork)

refName string

RefName is the name of the ref (branch, tag) if determined.

sha string

SHA is the SHA of the latest commit in the ref.

github.com/tinyci/ci-agents/ci-gen/grpc/types/repository.proto

Top

Repository

Repository is the model for a github repository.

FieldTypeLabelDescription
id int64

ID is the internal ID of the repository

name string

Name is the string name of the repository, in owner/repo format

private bool

Private tells the CI system to not expose this repository for subscription, unless they are an owner.

disabled bool

Disabled is true by default; and indicates whether or not the repository is disabled from testing.

owner User

Owner is the user who can manipulate this repository, as well as those whose keys will be used for testing.

autoCreated bool

AutoCreated is the flag that demonstrates this was created from a repo scan and not added manually.

hookSecret string

HookSecret is the secret populated into the github webhooks; and validated by us on incoming hook requests.

github bytes

JSON covering the entire repository's properties, when gathered from Github.

RepositoryList

FieldTypeLabelDescription
list Repository repeated

github.com/tinyci/ci-agents/ci-gen/grpc/types/run.proto

Top

Run

Run is a single CI run, intended to be sent to a runner.

FieldTypeLabelDescription
id int64

ID is the internal ID of the run.

name string

Name is the name of the run. Typically this is in `dir:run_name` format.

createdAt google.protobuf.Timestamp

When was this run created

startedAt google.protobuf.Timestamp

When did this run start

finishedAt google.protobuf.Timestamp

When did this run finish

status bool

What is the status of this run

statusSet bool

Is the status valid? (nil internally for invalid settings, but proto doesn't like nil)

settings RunSettings

The settings for the Run (image, command etc)

task Task

Task for the Run.

RunList

RunList is just an array of runs

FieldTypeLabelDescription
list Run repeated

The list of runs!

github.com/tinyci/ci-agents/ci-gen/grpc/types/run_settings.proto

Top

RunSettings

RunSettings covers all the features that tinyCI supports to manage runs and

execute them.

FieldTypeLabelDescription
command string repeated

Command is the command in execv() form (array of strings)

image string

Image is an arbitrary image name, the overlay runner needs docker registry format

queue string

Queue is the name of the queue this run should be placed in.

metadata google.protobuf.Struct

Metadata is a free form grab-bag of properties for runners to use.

name string

Name is the name of the run

timeout int64

Timeout is the timeout, in seconds, to wait before automatically canceling a run.

github.com/tinyci/ci-agents/ci-gen/grpc/types/session.proto

Top

Session

Session is a session key/value pair as well as an expiry time for the

session. All values are encrypted with the session key.

FieldTypeLabelDescription
key string

The key

values string

The value

expiresOn google.protobuf.Timestamp

When it expires

github.com/tinyci/ci-agents/ci-gen/grpc/types/task.proto

Top

CancelPRRequest

CancelPRRequest is used in CancelTasksByPR in the datasvc; can be used to

cancel all runs for a PR.

FieldTypeLabelDescription
id int64

repository string

Task

Task corresponds to directories within the tree that have a `task.yml`

placed in them. Each task is decomposed into runs, and this record is

created indicating the group of them, as well as properties they share.

FieldTypeLabelDescription
id int64

ID of the task

parent Repository

Parent Repository

ref Ref

Associated Ref to be tested

baseSHA string

BaseSHA for diff

pullRequestID int64

A pull request ID for PR events; 0 otherwise

canceled bool

Was the run canceled?

finishedAt google.protobuf.Timestamp

When did it finish?

createdAt google.protobuf.Timestamp

When was it created?

startedAt google.protobuf.Timestamp

When did it start

status bool

What is the status?

statusSet bool

Is the status valid?

settings TaskSettings

TaskSettings associated with the task (parsed task.yml)

path string

dirname of the task.yml

runs int64

count of runs for this task

TaskList

TaskList is simply a repeated list of tasks.

FieldTypeLabelDescription
Tasks Task repeated

List of tasks

TaskSettings

TaskSettings is the parsed representation to struct of task.yml files.

FieldTypeLabelDescription
mountpoint string

Mountpoint to use for the source code inside the container

env string repeated

Environment variables -- in environ syntax.

workdir string

Working dir inside the container; defaults to mountpoint

runs TaskSettings.RunsEntry repeated

Map of run name -> run settings, used for defining runs to create

defaultTimeout int64

Default Timeout if none is specified

defaultQueue string

Default Queue is none is specified; otherwise this is 'default'

defaultImage string

Default Image to use in runs.

metadata google.protobuf.Struct

Free-form metadata to be returned to runners.

dependencies string repeated

Dependency list.

TaskSettings.RunsEntry

FieldTypeLabelDescription
key string

value RunSettings

github.com/tinyci/ci-agents/ci-gen/grpc/types/user.proto

Top

User

User is ... a user record

FieldTypeLabelDescription
id int64

ID of user

username string

Username -- retrieved from github

lastScannedRepos google.protobuf.Timestamp

This flag is used to described when someone last scanned repositories for adding to CI.

errors UserError repeated

Errors for the user. See types.Errors

tokenJSON bytes

JSON corresponding to the oauth2 response from github when first signing up; this contains an access and refresh token. Encrypted with the token key.

UserError

UserError is the pre-converted UserError record. It is later converted to a types.Error.

FieldTypeLabelDescription
id int64

userID int64

error string

UserErrors

List of UserError

FieldTypeLabelDescription
errors UserError repeated

the list!

UserList

List of Users

FieldTypeLabelDescription
users User repeated

the list!

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str