~sircmpwn/sr.ht-dev

meta.sr.ht: api/graph: use GraphQL descriptions for docs v2 APPLIED

Simon Ser: 1
 api/graph: use GraphQL descriptions for docs

 1 files changed, 163 insertions(+), 109 deletions(-)
#653608 alpine.yml success
#653609 archlinux.yml success
#653610 debian.yml success
Export patchset (mbox)
How do I use this?

Copy & paste the following snippet into your terminal to import this patchset into git:

curl -s https://lists.sr.ht/~sircmpwn/sr.ht-dev/patches/27513/mbox | git am -3
Learn more about email & git

[PATCH meta.sr.ht v2] api/graph: use GraphQL descriptions for docs Export this patch

See [1] for details.

[1]: https://spec.graphql.org/June2018/#sec-Descriptions
---

Oops, forgot to close some double-quotes.

 api/graph/schema.graphqls | 272 +++++++++++++++++++++++---------------
 1 file changed, 163 insertions(+), 109 deletions(-)

diff --git a/api/graph/schema.graphqls b/api/graph/schema.graphqls
index 0fedb4017fff..2eda6adbc8a6 100644
--- a/api/graph/schema.graphqls
+++ b/api/graph/schema.graphqls
@@ -1,18 +1,26 @@
# This schema definition is available in the public domain, or under the terms
# of CC-0, at your choice.

scalar Cursor
scalar Time

# This is used to decorate fields which are only accessible with a personal
# access token, and are not available to clients using OAuth 2.0 access tokens.
"""
This is used to decorate fields which are only accessible with a personal
access token, and are not available to clients using OAuth 2.0 access tokens.
"""
directive @private on FIELD_DEFINITION

# This used to decorate fields which are for internal use, and are not
# available to normal API users.
"""
This used to decorate fields which are for internal use, and are not
available to normal API users.
"""
directive @internal on FIELD_DEFINITION

directive @anoninternal on FIELD_DEFINITION

# 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 {
@@ -28,10 +36,12 @@ 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. For the meta.sr.ht API, you have access to all public
# information without any special permissions - user profile information,
# public keys, and so on.
"""
Decorates fields for which access requires a particular OAuth 2.0 scope with
read or write access. For the meta.sr.ht API, you have access to all public
information without any special permissions - user profile information,
public keys, and so on.
"""
directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION | ENUM_VALUE

# https://semver.org
@@ -39,9 +49,11 @@ type Version {
  major: Int!
  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
}

@@ -49,8 +61,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!
}

@@ -160,7 +174,7 @@ type OAuthPersonalTokenRegistration {
}

enum WebhookEvent {
  # Used for user profile webhooks
  "Used for user profile webhooks"
  PROFILE_UPDATE  @access(scope: PROFILE, kind: RO)
  PGP_KEY_ADDED   @access(scope: PGP_KEYS, kind: RO)
  PGP_KEY_REMOVED @access(scope: PGP_KEYS, kind: RO)
@@ -174,14 +188,16 @@ interface WebhookSubscription {
  query: String!
  url: String!

  # If this webhook was registered by an authorized OAuth 2.0 client, this
  # field is non-null.
  """
  If this webhook was registered by an authorized OAuth 2.0 client, this
  field is non-null.
  """
  client: OAuthClient @private

  # All deliveries which have been sent to this webhook.
  "All deliveries which have been sent to this webhook."
  deliveries(cursor: Cursor): WebhookDeliveryCursor!

  # Returns a sample payload for this subscription, for testing purposes
  "Returns a sample payload for this subscription, for testing purposes"
  sample(event: WebhookEvent!): String!
}

@@ -202,10 +218,12 @@ type WebhookDelivery {
  subscription: WebhookSubscription!
  requestBody: String!

  # These details are provided only after a response is received from the
  # remote server. If a response is sent whose Content-Type is not text/*, or
  # cannot be decoded as UTF-8, the response body will be null. It will be
  # truncated after 64 KiB.
  """
  These details are provided only after a response is received from the
  remote server. If a response is sent whose Content-Type is not text/*, or
  cannot be decoded as UTF-8, the response body will be null. It will be
  truncated after 64 KiB.
  """
  responseBody: String
  responseHeaders: String
  responseStatus: Int
@@ -241,139 +259,161 @@ type SSHKeyEvent implements WebhookPayload {
  key: SSHKey!
}

# A cursor for enumerating a list of audit log entries
#
# 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 audit log entries

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 AuditLogCursor {
  results: [AuditLogEntry!]!
  cursor: Cursor
}

# A cursor for enumerating a list of invoices
#
# 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 invoices

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 InvoiceCursor {
  results: [Invoice!]!
  cursor: Cursor
}

# A cursor for enumerating a list of SSH keys
#
# 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 SSH keys

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 SSHKeyCursor {
  results: [SSHKey!]!
  cursor: Cursor
}

# A cursor for enumerating a list of PGP keys
#
# 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 PGP keys

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 PGPKeyCursor {
  results: [PGPKey!]!
  cursor: Cursor
}

# A cursor for enumerating a list of webhook deliveries
#
# 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 webhook deliveries

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 WebhookDeliveryCursor {
  results: [WebhookDelivery!]!
  cursor: Cursor
}

# A cursor for enumerating a list of webhook subscriptions
#
# 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 webhook subscriptions

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 WebhookSubscriptionCursor {
  results: [WebhookSubscription!]!
  cursor: Cursor
}

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)
  userByEmail(email: String!): User @access(scope: PROFILE, kind: RO)

  # Returns a specific SSH key by its fingerprint, in hexadecimal
  "Returns a specific SSH key by its fingerprint, in hexadecimal"
  sshKeyByFingerprint(fingerprint: String!): SSHKey @access(scope: SSH_KEYS, kind: RO)

  # Returns a specific PGP key by its fingerprint, in hexadecimal.
  "Returns a specific PGP key by its fingerprint, in hexadecimal."
  pgpKeyByFingerprint(fingerprint: String!): PGPKey @access(scope: PGP_KEYS, kind: RO)

  # Returns invoices for the authenticated user.
  "Returns invoices for the authenticated user."
  invoices(cursor: Cursor): InvoiceCursor! @access(scope: BILLING, kind: RO)

  # Returns the audit log for the authenticated user.
  "Returns the audit log for the authenticated user."
  auditLog(cursor: Cursor): AuditLogCursor! @access(scope: AUDIT_LOG, kind: RO)

  # Returns a list of user profile webhook subscriptions. For clients
  # authenticated with a personal access token, this returns all webhooks
  # configured by all GraphQL clients for your account. For clients
  # authenticated with an OAuth 2.0 access token, this returns only webhooks
  # registered for your client.
  """
  Returns a list of user profile webhook subscriptions. For clients
  authenticated with a personal access token, this returns all webhooks
  configured by all GraphQL clients for your account. For clients
  authenticated with an OAuth 2.0 access token, this returns only webhooks
  registered for your client.
  """
  profileWebhooks(cursor: Cursor): WebhookSubscriptionCursor!

  # Returns details of a user profile webhook subscription by its ID.
  "Returns details of a user profile webhook subscription by its ID."
  profileWebhook(id: Int!): WebhookSubscription

  # Returns information about the webhook currently being processed. This is
  # not valid during normal queries over HTTP, and will return an error if used
  # outside of a webhook context.
  """
  Returns information about the webhook currently being processed. This is
  not valid during normal queries over HTTP, and will return an error if used
  outside of a webhook context.
  """
  webhook: WebhookPayload!

  # Returns OAuth grants issued for the authenticated user
  "Returns OAuth grants issued for the authenticated user"
  oauthGrants: [OAuthGrant]! @private

  # List of OAuth clients this user administrates
  "List of OAuth clients this user administrates"
  oauthClients: [OAuthClient]! @private

  # Returns a list of personal OAuth tokens issued
  "Returns a list of personal OAuth tokens issued"
  personalAccessTokens: [OAuthPersonalToken]! @private

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

  # Returns a specific OAuth client (by database ID)
  "Returns a specific OAuth client (by database ID)"
  oauthClientByID(id: Int!): OAuthClient @internal

  # Returns a specific OAuth client (by UUID)
  "Returns a specific OAuth client (by UUID)"
  oauthClientByUUID(uuid: String!): OAuthClient @internal

  # Returns the revocation status of a given OAuth 2.0 token hash (SHA-512). If
  # the token or client ID has been revoked, this returns true, and the key
  # should not be trusted. Client ID is optional for personal access tokens.
  """
  Returns the revocation status of a given OAuth 2.0 token hash (SHA-512). If
  the token or client ID has been revoked, this returns true, and the key
  should not be trusted. Client ID is optional for personal access tokens.
  """
  tokenRevocationStatus(hash: String!, clientId: String): Boolean! @internal
}

"""
Omit these fields to leave them unchanged, or set them to null to clear
their value.
"""
input UserInput {
  # Omit these fields to leave them unchanged, or set them to null to clear
  # their value.
  url: String
  location: String
  bio: String

  # Note: changing the user's email address will not take effect immediately;
  # the user is sent an email to confirm the change first.
  """
  Note: changing the user's email address will not take effect immediately;
  the user is sent an email to confirm the change first.
  """
  email: String
}

@@ -392,67 +432,81 @@ type Mutation {
  createSSHKey(key: String!): SSHKey! @access(scope: SSH_KEYS, kind: RW)
  deleteSSHKey(id: Int!): SSHKey @access(scope: SSH_KEYS, kind: RW)

  # Causes the "last used" time of this SSH key to be updated.
  """
  Causes the "last used" time of this SSH key to be updated.
  """
  updateSSHKey(id: Int!): SSHKey! @access(scope: SSH_KEYS, kind: RO)

  # Creates a new user profile webhook subscription. When an event from the
  # provided list of events occurs, the 'query' parameter (a GraphQL query)
  # will be evaluated and the results will be sent to the provided URL as the
  # body of an HTTP POST request. The list of events must include at least one
  # event, and no duplicates.
  #
  # This query is evaluated in the webhook context, such that query { webhook }
  # may be used to access details of the event which trigged the webhook. The
  # query may not make any mutations.
  """
  Creates a new user profile webhook subscription. When an event from the
  provided list of events occurs, the 'query' parameter (a GraphQL query)
  will be evaluated and the results will be sent to the provided URL as the
  body of an HTTP POST request. The list of events must include at least one
  event, and no duplicates.

  This query is evaluated in the webhook context, such that query { webhook }
  may be used to access details of the event which trigged the webhook. The
  query may not make any mutations.
  """
  createWebhook(config: ProfileWebhookInput!): WebhookSubscription!

  # Deletes a user profile webhook. Any events already queued may still be
  # delivered after this request completes. Clients authenticated with a
  # personal access token may delete any webhook registered for their account,
  # but authorized OAuth 2.0 clients may only delete their own webhooks.
  # Manually deleting a webhook configured by a third-party client may cause
  # unexpected behavior with the third-party integration.
  """
  Deletes a user profile webhook. Any events already queued may still be
  delivered after this request completes. Clients authenticated with a
  personal access token may delete any webhook registered for their account,
  but authorized OAuth 2.0 clients may only delete their own webhooks.
  Manually deleting a webhook configured by a third-party client may cause
  unexpected behavior with the third-party integration.
  """
  deleteWebhook(id: Int!): WebhookSubscription

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

  # Registers a new account.
  "Registers a new account."
  registerAccount(email: String!,
    username: String!,
    password: String!,
    pgpKey: String,
    invite: String): User @anoninternal

  # Registers an OAuth client. Only OAuth 2.0 confidental clients are
  # supported.
  """
  Registers an OAuth client. Only OAuth 2.0 confidental clients are
  supported.
  """
  registerOAuthClient(
    redirectUri: String!,
    clientName: String!,
    clientDescription: String,
    clientUrl: String): OAuthClientRegistration! @internal

  # Revokes this OAuth client, revoking all tokens for it and preventing future
  # use.
  """
  Revokes this OAuth client, revoking all tokens for it and preventing future
  use.
  """
  revokeOAuthClient(uuid: String!): OAuthClient @internal

  # Revokes a specific OAuth grant.
  "Revokes a specific OAuth grant."
  revokeOAuthGrant(hash: String!): OAuthGrant @internal

  # Issues an OAuth personal access token.
  "Issues an OAuth personal access token."
  issuePersonalAccessToken(grants: String, comment: String):
    OAuthPersonalTokenRegistration! @internal

  # Revokes a personal access token.
  "Revokes a personal access token."
  revokePersonalAccessToken(id: Int!): OAuthPersonalToken @internal

  # Issues an OAuth 2.0 authorization code. Used after the user has consented
  # to the access grant request.
  """
  Issues an OAuth 2.0 authorization code. Used after the user has consented
  to the access grant request.
  """
  issueAuthorizationCode(clientUUID: String!, grants: String!): String! @internal

  # Completes the OAuth 2.0 grant process and issues an OAuth token for a
  # specific OAuth client.
  """
  Completes the OAuth 2.0 grant process and issues an OAuth token for a
  specific OAuth client.
  """
  issueOAuthGrant(authorization: String!,
    clientSecret: String!): OAuthGrantRegistration @internal
}

base-commit: 9931df3c23094af5179df9ef019ca732b8125dac
-- 
2.34.1
meta.sr.ht/patches: SUCCESS in 3m26s

[api/graph: use GraphQL descriptions for docs][0] v2 from [Simon Ser][1]

[0]: https://lists.sr.ht/~sircmpwn/sr.ht-dev/patches/27513
[1]: mailto:contact@emersion.fr

✓ #653608 SUCCESS meta.sr.ht/patches/alpine.yml    https://builds.sr.ht/~sircmpwn/job/653608
✓ #653609 SUCCESS meta.sr.ht/patches/archlinux.yml https://builds.sr.ht/~sircmpwn/job/653609
✓ #653610 SUCCESS meta.sr.ht/patches/debian.yml    https://builds.sr.ht/~sircmpwn/job/653610
Thanks!

To git@git.sr.ht:~sircmpwn/meta.sr.ht
   80a2a5a..850a5ed  master -> master