~comcloudway/builds.sr.ht

45e539eaccb99b67e3eaf6843659e77398025374 — Simon Ser 2 years ago f180500
api/graph: use GraphQL descriptions for docs
1 files changed, 81 insertions(+), 59 deletions(-)

M api/graph/schema.graphqls
M api/graph/schema.graphqls => api/graph/schema.graphqls +81 -59
@@ 5,7 5,7 @@ scalar Binary # base64'd string
scalar Cursor
scalar File

# Used to provide a human-friendly description of an access scope
"Used to provide a human-friendly description of an access scope"
directive @scopehelp(details: String!) on ENUM_VALUE

enum AccessScope {


@@ 20,12 20,16 @@ enum AccessKind {
  RW @scopehelp(details: "read and write")
}

# Decorates fields for which access requires a particular OAuth 2.0 scope with
# read or write access.
"""
Decorates fields for which access requires a particular OAuth 2.0 scope with
read or write access.
"""
directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION

# This used to decorate private resolvers which are only accessible to build
# workers, and are used to faciliate the build process.
"""
This used to decorate private resolvers which are only accessible to build
workers, and are used to faciliate the build process.
"""
directive @worker on FIELD_DEFINITION

# https://semver.org


@@ 34,9 38,11 @@ type Version {
  minor: Int!
  patch: Int!

  # If this API version is scheduled for deprecation, this is the date on which
  # it will stop working; or null if this API version is not scheduled for
  # deprecation.
  """
  If this API version is scheduled for deprecation, this is the date on which
  it will stop working; or null if this API version is not scheduled for
  deprecation.
  """
  deprecationDate: Time
}



@@ 44,8 50,10 @@ interface Entity {
  id: Int!
  created: Time!
  updated: Time!
  # The canonical name of this entity. For users, this is their username
  # prefixed with '~'. Additional entity types will be supported in the future.
  """
  The canonical name of this entity. For users, this is their username
  prefixed with '~'. Additional entity types will be supported in the future.
  """
  canonicalName: String!
}



@@ 60,7 68,7 @@ type User implements Entity {
  location: String
  bio: String

  # Jobs submitted by this user.
  "Jobs submitted by this user."
  jobs(cursor: Cursor): JobCursor! @access(scope: JOBS, kind: RO)
}



@@ 83,11 91,13 @@ type Job {
  note: String
  tags: [String]!

  # Name of the build image
  "Name of the build image"
  image: String!

  # Name of the build runner which picked up this job, or null if the job is
  # pending or queued.
  """
  Name of the build runner which picked up this job, or null if the job is
  pending or queued.
  """
  runner: String

  owner: Entity! @access(scope: PROFILE, kind: RO)


@@ 95,37 105,41 @@ type Job {
  tasks: [Task]!
  artifacts: [Artifact]!

  # The job's top-level log file, not associated with any tasks
  "The job's top-level log file, not associated with any tasks"
  log: Log @access(scope: LOGS, kind: RO)

  # List of secrets available to this job, or null if they were disabled
  "List of secrets available to this job, or null if they were disabled"
  secrets: [Secret] @access(scope: SECRETS, kind: RO)
}

type Log {
  # The most recently written 128 KiB of the build log.
  "The most recently written 128 KiB of the build log."
  last128KiB: String!
  # The URL at which the full build log can be downloaded with a GET request
  # (text/plain).
  """
  The URL at which the full build log can be downloaded with a GET request
  (text/plain).
  """
  fullURL: String!
}

type Artifact {
  id: Int!
  created: Time!
  # Original path in the guest
  "Original path in the guest"
  path: String!
  # Size in bytes
  "Size in bytes"
  size: Int!
  # URL at which the artifact may be downloaded, or null if pruned
  "URL at which the artifact may be downloaded, or null if pruned"
  url: String
}

# A cursor for enumerating a list of jobs
#
# If there are additional results available, the cursor object may be passed
# back into the same endpoint to retrieve another page. If the cursor is null,
# there are no remaining results to return.
"""
A cursor for enumerating a list of jobs

If there are additional results available, the cursor object may be passed
back into the same endpoint to retrieve another page. If the cursor is null,
there are no remaining results to return.
"""
type JobCursor {
  results: [Job!]!
  cursor: Cursor


@@ 164,9 178,11 @@ enum TriggerCondition {
  ALWAYS
}

# Triggers run upon the completion of all of the jobs in a job group. Note that
# these triggers are distinct from the ones defined by an individual job's
# build manifest, but are similar in functionality.
"""
Triggers run upon the completion of all of the jobs in a job group. Note that
these triggers are distinct from the ones defined by an individual job's
build manifest, but are similar in functionality.
"""
interface Trigger {
  condition: TriggerCondition!
}


@@ 190,11 206,13 @@ interface Secret {
  name: String
}

# A cursor for enumerating a list of secrets
#
# If there are additional results available, the cursor object may be passed
# back into the same endpoint to retrieve another page. If the cursor is null,
# there are no remaining results to return.
"""
A cursor for enumerating a list of secrets

If there are additional results available, the cursor object may be passed
back into the same endpoint to retrieve another page. If the cursor is null,
there are no remaining results to return.
"""
type SecretCursor {
  results: [Secret!]!
  cursor: Cursor


@@ 227,23 245,23 @@ type SecretFile implements Secret {
}

type Query {
  # Returns API version information.
  "Returns API version information."
  version: Version!

  # Returns the authenticated user.
  "Returns the authenticated user."
  me: User! @access(scope: PROFILE, kind: RO)

  # Returns a specific user
  "Returns a specific user."
  userByID(id: Int!): User @access(scope: PROFILE, kind: RO)
  userByName(username: String!): User @access(scope: PROFILE, kind: RO)

  # Returns jobs submitted by the authenticated user.
  "Returns jobs submitted by the authenticated user."
  jobs(cursor: Cursor): JobCursor! @access(scope: JOBS, kind: RO)

  # Returns information about a specific job.
  "Returns information about a specific job."
  job(id: Int!): Job @access(scope: JOBS, kind: RO)

  # Returns secrets owned by the authenticated user.
  "Returns secrets owned by the authenticated user."
  secrets(cursor: Cursor): SecretCursor! @access(scope: SECRETS, kind: RO)
}



@@ 270,44 288,48 @@ input TriggerInput {
}

type Mutation {
  # Submits a new job to the queue.
  #
  # 'secrets' may be set to false to disable secrets for this build. Secrets
  # are enabled if unspecified.
  #
  # 'execute' may be set to false to defer queueing this job. Builds are
  # executed immediately if unspecified.
  """
  Submits a new job to the queue.

  'secrets' may be set to false to disable secrets for this build. Secrets
  are enabled if unspecified.

  'execute' may be set to false to defer queueing this job. Builds are
  executed immediately if unspecified.
  """
  submit(manifest: String!, tags: [String!] note: String, secrets: Boolean,
    execute: Boolean): Job! @access(scope: JOBS, kind: RW)

  # Queues a pending job.
  "Queues a pending job."
  start(jobID: Int!): Job @access(scope: JOBS, kind: RW)

  # Cancels a submitted job.
  "Cancels a submitted job."
  cancel(jobId: Int!): Job @access(scope: JOBS, kind: RW)

  # Creates a job group from several pending jobs.
  #
  # 'execute' may be set to false to defer queueing this job. The job group is
  # executed immediately if unspecified.
  """
  Creates a job group from several pending jobs.

  'execute' may be set to false to defer queueing this job. The job group is
  executed immediately if unspecified.
  """
  createGroup(jobIds: [Int!]!  triggers: [TriggerInput!],
    execute: Boolean, note: String): JobGroup! @access(scope: JOBS, kind: RW)

  # Starts a pending job group.
  "Starts a pending job group."
  startGroup(groupId: Int!): JobGroup @access(scope: JOBS, kind: RW)

  ###
  ### The following resolvers are for internal worker use

  # Claims a job
  "Claims a job."
  claim(jobId: Int!): Job @worker

  # Updates job status
  "Updates job status."
  updateJob(jobId: Int!, status: JobStatus!): Job @worker

  # Updates task status
  "Updates task status."
  updateTask(taskId: Int!, status: TaskStatus!): Job @worker

  # Uploads a build artifact
  "Uploads a build artifact."
  createArtifact(jobId: Int!, path: String!, contents: File!): Artifact @worker
}