Debian Codegraph @

srht/gitsrht/schema.graphqls

raw
1 # This schema definition is available in the public domain, or under the terms
2 # of CC-0, at your choice.
3
4 scalar Cursor
5
6 "String of the format %Y-%m-%dT%H:%M:%SZ"
7 scalar Time
8
9 """
10 A file uploaded alongside the GraphQL request. This API is compatible with the
11 multipart request specification for requests that include uploads:
12
13 https://github.com/jaydenseric/graphql-multipart-request-spec
14 """
15 scalar Upload
16
17 """
18 URL from which some secondary data may be retrieved. You must provide the
19 same Authentication header to this address as you did to the GraphQL resolver
20 which provided it. The URL is not guaranteed to be consistent for an extended
21 length of time; applications should submit a new GraphQL query each time they
22 wish to access the data at the provided URL.
23 """
24 scalar URL
25
26 "Used to provide a human-friendly description of an access scope"
27 directive @scopehelp(details: String!) on ENUM_VALUE
28
29 """
30 This is used to decorate fields which are only accessible with a personal
31 access token, and are not available to clients using OAuth 2.0 access tokens.
32 """
33 directive @private on FIELD_DEFINITION
34
35 # For internal use
36 directive @internal on FIELD_DEFINITION
37 directive @anoninternal on FIELD_DEFINITION
38
39 enum AccessScope {
40 PROFILE @scopehelp(details: "profile information")
41 REPOSITORIES @scopehelp(details: "repository metadata")
42 OBJECTS @scopehelp(details: "git objects & references")
43 ACLS @scopehelp(details: "access control lists")
44 }
45
46 enum AccessKind {
47 RO @scopehelp(details: "read")
48 RW @scopehelp(details: "read and write")
49 }
50
51 """
52 Decorates fields for which access requires a particular OAuth 2.0 scope with
53 read or write access.
54 """
55 directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION
56
57 # https://semver.org
58 type Version {
59 major: Int!
60 minor: Int!
61 patch: Int!
62 buildVersion: String!
63 buildDate: String!
64
65 """
66 If this API version is scheduled for deprecation, this is the date on which
67 it will stop working; or null if this API version is not scheduled for
68 deprecation.
69 """
70 deprecationDate: Time
71
72 "Optional features"
73 features: Features!
74
75 "Config settings"
76 settings: Settings!
77 }
78
79 "Describes the status of optional features"
80 type Features {
81 artifacts: Boolean!
82 }
83
84 "Instance specific settings"
85 type Settings {
86 sshUser: String!
87 }
88
89 enum AccessMode {
90 "Read-only"
91 RO
92 "Read/write"
93 RW
94 }
95
96 enum Visibility {
97 "Visible to everyone, listed on your profile"
98 PUBLIC
99 "Visible to everyone (if they know the URL), not listed on your profile"
100 UNLISTED
101 "Not visible to anyone except those explicitly added to the access list"
102 PRIVATE
103 }
104
105 interface Entity {
106 id: Int!
107 created: Time!
108 updated: Time!
109 """
110 The canonical name of this entity. For users, this is their username
111 prefixed with '~'. Additional entity types will be supported in the future.
112 """
113 canonicalName: String!
114
115 "Returns a specific repository owned by the entity."
116 repository(name: String!): Repository @access(scope: REPOSITORIES, kind: RO)
117
118 "Returns a list of repositories owned by the entity."
119 repositories(cursor: Cursor, filter: Filter): RepositoryCursor! @access(scope: REPOSITORIES, kind: RO)
120 }
121
122 type User implements Entity {
123 id: Int!
124 created: Time!
125 updated: Time!
126 canonicalName: String!
127 username: String!
128 email: String!
129 url: String
130 location: String
131 bio: String
132
133 repository(name: String!): Repository @access(scope: REPOSITORIES, kind: RO)
134 repositories(cursor: Cursor, filter: Filter): RepositoryCursor! @access(scope: REPOSITORIES, kind: RO)
135 }
136
137 type Repository {
138 id: Int!
139 rid: ID!
140 created: Time!
141 updated: Time!
142 owner: Entity! @access(scope: PROFILE, kind: RO)
143 name: String!
144 description: String
145 visibility: Visibility!
146
147 """
148 The repository's custom README, if set.
149
150 NOTICE: This returns unsanitized HTML. It is the client's responsibility to
151 sanitize this for display on the web, if so desired.
152 """
153 readme: String
154
155 "The access that applies to this user for this repository"
156 access: AccessMode!
157
158 # Only available to the repository owner
159 acls(cursor: Cursor): ACLCursor! @access(scope: ACLS, kind: RO)
160
161 ## Plumbing API:
162
163 """
164 Returns any number of git objects by their IDs.
165 """
166 objects(ids: [String!]): [Object]! @access(scope: OBJECTS, kind: RO)
167 """
168 Returns a specific git object by its ID.
169 """
170 object(id: String!): Object @access(scope: OBJECTS, kind: RO)
171
172 """
173 Enumerates references on this repository.
174 """
175 references(cursor: Cursor): ReferenceCursor! @access(scope: OBJECTS, kind: RO)
176 """
177 Returns a reference by its fully qualified name, e.g. refs/heads/master.
178 """
179 reference(name: String!): Reference @access(scope: OBJECTS, kind: RO)
180
181 ## Porcelain API:
182
183 # NOTE: revspecs are git-compatible, e.g. "HEAD~4", "master", "9790b10")
184
185 "The HEAD reference for this repository (equivalent to the default branch)"
186 HEAD: Reference @access(scope: OBJECTS, kind: RO)
187
188 """
189 Returns a list of comments sorted by committer time (similar to `git log`'s
190 default ordering).
191
192 If `from` is specified, it is interpreted as a revspec to start logging
193 from. A clever reader may notice that using commits[-1].from + "^" as the
194 from parameter is equivalent to passing the cursor to the next call.
195 """
196 log(cursor: Cursor, from: String): CommitCursor! @access(scope: OBJECTS, kind: RO)
197
198 "Returns a tree entry for a given path, at the given revspec."
199 path(revspec: String = "HEAD", path: String!): TreeEntry @access(scope: OBJECTS, kind: RO)
200
201 "Returns the commit for a given revspec."
202 revparse_single(revspec: String!): Commit @access(scope: OBJECTS, kind: RO)
203
204 ## For internal use
205 repoPath: String! @anoninternal
206 }
207
208 # For internal use
209 type Redirect {
210 created: Time!
211 name: String!
212 owner: Entity!
213 originalPath: String!
214 repository: Repository
215 }
216
217 type OAuthClient {
218 uuid: String!
219 }
220
221 enum WebhookEvent {
222 # User webhooks only
223 REPO_CREATED
224 REPO_UPDATE
225 REPO_DELETED
226
227 # Git webhooks only
228 GIT_PRE_RECEIVE
229 GIT_POST_RECEIVE
230 }
231
232 interface WebhookSubscription {
233 id: Int!
234 events: [WebhookEvent!]!
235 query: String!
236 url: String!
237
238 """
239 If this webhook was registered by an authorized OAuth 2.0 client, this
240 field is non-null.
241 """
242 client: OAuthClient @private
243
244 "All deliveries which have been sent to this webhook."
245 deliveries(cursor: Cursor): WebhookDeliveryCursor!
246
247 "Returns a sample payload for this subscription, for testing purposes"
248 sample(event: WebhookEvent!): String!
249 }
250
251 type UserWebhookSubscription implements WebhookSubscription {
252 id: Int!
253 events: [WebhookEvent!]!
254 query: String!
255 url: String!
256 client: OAuthClient @private
257 deliveries(cursor: Cursor): WebhookDeliveryCursor!
258 sample(event: WebhookEvent!): String!
259 }
260
261 type GitWebhookSubscription implements WebhookSubscription {
262 id: Int!
263 events: [WebhookEvent!]!
264 query: String!
265 url: String!
266 client: OAuthClient @private
267 deliveries(cursor: Cursor): WebhookDeliveryCursor!
268 sample(event: WebhookEvent!): String!
269 }
270
271 type WebhookDelivery {
272 uuid: String!
273 date: Time!
274 event: WebhookEvent!
275 subscription: WebhookSubscription!
276 requestBody: String!
277
278 """
279 These details are provided only after a response is received from the
280 remote server. If a response is sent whose Content-Type is not text/*, or
281 cannot be decoded as UTF-8, the response body will be null. It will be
282 truncated after 64 KiB.
283 """
284 responseBody: String
285 responseHeaders: String
286 responseStatus: Int
287 }
288
289 interface WebhookPayload {
290 uuid: String!
291 event: WebhookEvent!
292 date: Time!
293 }
294
295 type RepositoryEvent implements WebhookPayload {
296 uuid: String!
297 event: WebhookEvent!
298 date: Time!
299
300 repository: Repository!
301 }
302
303 type UpdatedRef {
304 # Is null when pushing a new reference
305 ref: Reference
306 # Is null when pushing a new reference
307 old: Object
308 # Is null when deleting a reference
309 new: Object
310
311 """
312 Note: this only returns up to the most recent 50 commits included in the
313 update, i.e. old..new or new~50..new, whichever has fewer commits.
314 """
315 log: CommitCursor
316
317 """
318 Difference from old..new in the unified diff format.
319
320 This field is null if the diff requires more than one second to prepare.
321 """
322 diff: String
323 }
324
325 """
326 This event is used for pre-receive and post-receive git hooks.
327 """
328 type GitEvent implements WebhookPayload {
329 uuid: String!
330 event: WebhookEvent!
331 date: Time!
332
333 repository: Repository! @access(scope: REPOSITORIES, kind: RO)
334 pusher: Entity! @access(scope: PROFILE, kind: RO)
335 updates: [UpdatedRef]! @access(scope: OBJECTS, kind: RO)
336 }
337
338 """
339 A cursor for enumerating a list of repositories
340
341 If there are additional results available, the cursor object may be passed
342 back into the same endpoint to retrieve another page. If the cursor is null,
343 there are no remaining results to return.
344 """
345 type RepositoryCursor {
346 results: [Repository!]!
347 cursor: Cursor
348 }
349
350 """
351 A cursor for enumerating access control list entries
352
353 If there are additional results available, the cursor object may be passed
354 back into the same endpoint to retrieve another page. If the cursor is null,
355 there are no remaining results to return.
356 """
357 type ACLCursor {
358 results: [ACL!]!
359 cursor: Cursor
360 }
361
362 """
363 A cursor for enumerating a list of references
364
365 If there are additional results available, the cursor object may be passed
366 back into the same endpoint to retrieve another page. If the cursor is null,
367 there are no remaining results to return.
368 """
369 type ReferenceCursor {
370 results: [Reference!]!
371 cursor: Cursor
372 }
373
374 """
375 A cursor for enumerating commits
376
377 If there are additional results available, the cursor object may be passed
378 back into the same endpoint to retrieve another page. If the cursor is null,
379 there are no remaining results to return.
380 """
381 type CommitCursor {
382 results: [Commit!]!
383 cursor: Cursor
384 }
385
386 """
387 A cursor for enumerating tree entries
388
389 If there are additional results available, the cursor object may be passed
390 back into the same endpoint to retrieve another page. If the cursor is null,
391 there are no remaining results to return.
392 """
393 type TreeEntryCursor {
394 results: [TreeEntry!]!
395 cursor: Cursor
396 }
397
398 """
399 A cursor for enumerating artifacts
400
401 If there are additional results available, the cursor object may be passed
402 back into the same endpoint to retrieve another page. If the cursor is null,
403 there are no remaining results to return.
404 """
405 type ArtifactCursor {
406 results: [Artifact!]!
407 cursor: Cursor
408 }
409
410 """
411 A cursor for enumerating a list of webhook deliveries
412
413 If there are additional results available, the cursor object may be passed
414 back into the same endpoint to retrieve another page. If the cursor is null,
415 there are no remaining results to return.
416 """
417 type WebhookDeliveryCursor {
418 results: [WebhookDelivery!]!
419 cursor: Cursor
420 }
421
422 """
423 A cursor for enumerating a list of webhook subscriptions
424
425 If there are additional results available, the cursor object may be passed
426 back into the same endpoint to retrieve another page. If the cursor is null,
427 there are no remaining results to return.
428 """
429 type WebhookSubscriptionCursor {
430 results: [WebhookSubscription!]!
431 cursor: Cursor
432 }
433
434 type ACL {
435 id: Int!
436 created: Time!
437 repository: Repository!
438 entity: Entity! @access(scope: PROFILE, kind: RO)
439 mode: AccessMode
440 }
441
442 "Arbitrary file attached to a git repository"
443 type Artifact {
444 id: Int!
445 created: Time!
446 filename: String!
447 checksum: String!
448 size: Int!
449 url: URL!
450 }
451
452 type Reference {
453 name: String!
454 target: String!
455 follow: Object
456
457 artifact(filename: String!): Artifact
458 artifacts(cursor: Cursor): ArtifactCursor!
459 }
460
461 enum ObjectType {
462 COMMIT
463 TREE
464 BLOB
465 TAG
466 }
467
468 interface Object {
469 type: ObjectType!
470 id: String!
471 shortId: String!
472 }
473
474 type Signature {
475 name: String!
476 email: String!
477 time: Time!
478 }
479
480 type Trailer {
481 name: String!
482 value: String!
483 }
484
485 type Commit implements Object {
486 type: ObjectType!
487 id: String!
488 shortId: String!
489 author: Signature!
490 committer: Signature!
491 message: String!
492 tree: Tree!
493 parents: [Commit!]!
494 diff: String!
495 trailers: [Trailer!]!
496 }
497
498 type Tree implements Object {
499 type: ObjectType!
500 id: String!
501 shortId: String!
502 # TODO: add globbing
503 entries(cursor: Cursor): TreeEntryCursor!
504
505 entry(path: String): TreeEntry
506 }
507
508 type TreeEntry {
509 id: String!
510 name: String!
511 object: Object!
512 "Unix-style file mode, i.e. 0755 or 0644 (octal)"
513 mode: Int!
514 }
515
516 interface Blob {
517 id: String!
518 type: ObjectType!
519 content: URL!
520 "Size of the blob in bytes"
521 size: Int!
522 }
523
524 type TextBlob implements Object & Blob {
525 type: ObjectType!
526 id: String!
527 shortId: String!
528 content: URL!
529 "Size of the blob in bytes"
530 size: Int!
531
532 """
533 Returns up to 128 KiB of text content. Use the content field if you need more.
534 """
535 text: String!
536 }
537
538 type BinaryBlob implements Object & Blob {
539 type: ObjectType!
540 id: String!
541 shortId: String!
542 content: URL!
543 "Size of the blob in bytes"
544 size: Int!
545
546 """
547 Returns up to 32 KiB of binary content.
548
549 Notice: this field is deprecated. Prefer to use the content field.
550 """
551 base64: String!
552 }
553
554 """
555 An annotated git tag.
556 """
557 type Tag implements Object {
558 type: ObjectType!
559 id: String!
560 shortId: String!
561 target: Object!
562 name: String!
563 tagger: Signature!
564 message: String!
565 }
566
567 input Filter {
568 "Number of results to return."
569 count: Int = 20
570
571 """
572 Search terms. The exact meaning varies by usage, but generally these are
573 compatible with the web UI's search syntax.
574 """
575 search: String
576 }
577
578 type Query {
579 "Returns API version information."
580 version: Version!
581
582 "Returns the authenticated user."
583 me: User! @access(scope: PROFILE, kind: RO)
584
585 "Returns a specific user."
586 user(username: String!): User @access(scope: PROFILE, kind: RO)
587
588 "Looks up a repository based on its resource ID."
589 repository(rid: ID!): Repository @access(scope: REPOSITORIES, kind: RO)
590
591 """
592 Returns repositories that the authenticated user has access to.
593
594 NOTE: in this version of the API, only repositories owned by the
595 authenticated user are returned, but in the future the default behavior
596 will be to return all repositories that the user either (1) has been given
597 explicit access to via ACLs or (2) has implicit access to either by
598 ownership or group membership.
599 """
600 repositories(cursor: Cursor, filter: Filter): RepositoryCursor @access(scope: REPOSITORIES, kind: RO)
601
602 """
603 Returns a list of user webhook subscriptions. For clients
604 authenticated with a personal access token, this returns all webhooks
605 configured by all GraphQL clients for your account. For clients
606 authenticated with an OAuth 2.0 access token, this returns only webhooks
607 registered for your client.
608 """
609 userWebhooks(cursor: Cursor): WebhookSubscriptionCursor!
610
611 "Returns details of a user webhook subscription by its ID."
612 userWebhook(id: Int!): WebhookSubscription
613
614 """
615 Returns a list of git webhook subscriptions associated with a repository. For
616 clients authenticated with a personal access token, this returns all webhooks
617 configured by all GraphQL clients for your account. For clients authenticated
618 with an OAuth 2.0 access token, this returns only webhooks registered for
619 your client.
620 """
621 gitWebhooks(repositoryID: Int!, cursor: Cursor): WebhookSubscriptionCursor!
622
623 "Returns details of a git webhook subscription by its ID."
624 gitWebhook(id: Int!): WebhookSubscription
625
626 """
627 Returns information about the webhook currently being processed. This is
628 not valid during normal queries over HTTP, and will return an error if used
629 outside of a webhook context.
630 """
631 webhook: WebhookPayload!
632
633 ## Internal use
634
635 # Looks up a repository by its path on disk
636 repositoryByDiskPath(path: String!): Repository @anoninternal
637
638 # Looks up a redirect by its (original) path on disk
639 redirectByDiskPath(path: String!): Redirect @anoninternal
640 }
641
642 input RepoInput {
643 # Omit these fields to leave them unchanged, or set them to null to clear
644 # their value.
645 name: String
646 description: String
647 visibility: Visibility
648
649 """
650 Updates the custom README associated with this repository. Note that the
651 provided HTML will be sanitized when displayed on the web; see
652 https://man.sr.ht/markdown/#post-processing
653 """
654 readme: String
655
656 """
657 Updates the repository HEAD reference, which serves as the default branch.
658 Must be a valid branch name.
659 """
660 HEAD: String
661 }
662
663 input UserWebhookInput {
664 url: String!
665 events: [WebhookEvent!]!
666 query: String!
667 }
668
669 input GitWebhookInput {
670 repositoryID: Int!
671
672 url: String!
673 events: [WebhookEvent!]!
674 query: String!
675 }
676
677 input UpdatedRefInput {
678 ref: String!
679 old: String!
680 new: String!
681 }
682
683 input GitEventInput {
684 repositoryID: Int!
685 event: WebhookEvent!
686 updates: [UpdatedRefInput]!
687 }
688
689 type Mutation {
690 """
691 Creates a new git repository. If the cloneUrl parameter is specified, the
692 repository will be cloned from the given URL.
693 """
694 createRepository(name: String!, visibility: Visibility!, description: String, cloneUrl: String): Repository @access(scope: REPOSITORIES, kind: RW)
695
696 "Updates the metadata for a git repository"
697 updateRepository(id: Int!, input: RepoInput!): Repository @access(scope: REPOSITORIES, kind: RW)
698
699 "Deletes a git repository"
700 deleteRepository(id: Int!): Repository @access(scope: REPOSITORIES, kind: RW)
701
702 "Adds or updates a user in the access control list"
703 updateACL(repoId: Int!, mode: AccessMode!, entity: String!): ACL! @access(scope: ACLS, kind: RW)
704
705 "Deletes an entry from the access control list"
706 deleteACL(id: Int!): ACL @access(scope: ACLS, kind: RW)
707
708 """
709 Uploads an artifact. revspec must match a specific git tag, and the
710 filename must be unique among artifacts for this repository.
711 """
712 uploadArtifact(repoId: Int!, revspec: String!, file: Upload!): Artifact! @access(scope: OBJECTS, kind: RW)
713
714 "Deletes an artifact."
715 deleteArtifact(id: Int!): Artifact @access(scope: OBJECTS, kind: RW)
716
717 """
718 Creates a new user webhook subscription. When an event from the
719 provided list of events occurs, the 'query' parameter (a GraphQL query)
720 will be evaluated and the results will be sent to the provided URL as the
721 body of an HTTP POST request. The list of events must include at least one
722 event, and no duplicates.
723
724 This query is evaluated in the webhook context, such that query { webhook }
725 may be used to access details of the event which trigged the webhook. The
726 query may not make any mutations.
727 """
728 createUserWebhook(config: UserWebhookInput!): WebhookSubscription!
729
730 """
731 Deletes a user webhook. Any events already queued may still be
732 delivered after this request completes. Clients authenticated with a
733 personal access token may delete any webhook registered for their account,
734 but authorized OAuth 2.0 clients may only delete their own webhooks.
735 Manually deleting a webhook configured by a third-party client may cause
736 unexpected behavior with the third-party integration.
737 """
738 deleteUserWebhook(id: Int!): WebhookSubscription!
739
740 """
741 Creates a git webhook. When an event from the provided list of events occurs,
742 the 'query' parameter (a GraphQL query) will be evaluated and the results
743 will be sent to the provided URL as the body of an HTTP POST request. The
744 list of events must include at least one event, and no duplicates.
745
746 This query is evaluated in the webhook context, such that query { webhook }
747 may be used to access details of the event which trigged the webhook. The
748 query may not make any mutations.
749 """
750 createGitWebhook(config: GitWebhookInput!): WebhookSubscription!
751
752 """
753 Deletes a git webhook. Any events already queued may still be delivered after
754 this request completes. Clients authenticated with a personal access token
755 may delete any webhook registered for their account, but authorized OAuth 2.0
756 clients may only delete their own webhooks. Manually deleting a webhook
757 configured by a third-party client may cause unexpected behavior with the
758 third-party integration.
759 """
760 deleteGitWebhook(id: Int!): WebhookSubscription!
761
762 ### ###
763 ### The following resolvers are for internal use. ###
764 ### ###
765
766 """
767 Deletes the authenticated user's account. Internal use only.
768 """
769 deleteUser: Int! @internal
770
771 """
772 Delivers git webhooks. If it returns false, the push event should be
773 rejected. Invoked by git.sr.ht-update-hook.
774 """
775 deliverGitHook(input: GitEventInput!): Boolean! @internal
776 }