diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9b02f63 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,54 @@ +name: CI + +# Third-party actions are pinned to a full commit SHA (the tag in a trailing +# comment), as in hadron-cli, so a moved upstream tag cannot change what runs. + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: go.mod + - name: Build + run: go build ./... + # The adapter runs wherever the hadron CLI runs. + - name: Cross-build + run: | + for t in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64; do + GOOS=${t%/*} GOARCH=${t#*/} go build -o /dev/null ./cmd/hadron-task-adapter-github + done + # Includes the conformance suite: the built adapter driven by the + # hadron-cli runner's rules against a fake GitHub. + - name: Test + run: go test -race ./... + + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: go.mod + - uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9 + with: + skip-cache: true + + vuln: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: go.mod + - name: govulncheck + run: go run golang.org/x/vuln/cmd/govulncheck@v1.5.0 ./... diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a53331a --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# A team's own adapter configuration (repositories, labels, team map) and any +# credential stay out of this public repository. Only config.example.json is +# committed. +/config.json +*.local.json +.env +/bin/ +/dist/ diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 0000000..aff864a --- /dev/null +++ b/.golangci.yml @@ -0,0 +1,25 @@ +version: "2" + +linters: + default: standard + enable: + - misspell + - unconvert + - unparam + settings: + errcheck: + exclude-functions: + - fmt.Fprint + - fmt.Fprintf + - fmt.Fprintln + - (io.ReadCloser).Close + - (*os.File).Close + +# Formatting is a gate: `golangci-lint run` reports a gofmt diff as an issue. +formatters: + enable: + - gofmt + +issues: + max-issues-per-linter: 0 + max-same-issues: 0 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..bd04856 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Hadron Memory + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index a88b2e8..c4eb46f 100644 --- a/README.md +++ b/README.md @@ -1 +1,155 @@ -# hadron-task-adapter-github \ No newline at end of file +# hadron-task-adapter-github + +The GitHub **intake adapter** for [Hadron](https://hadronmemory.com) teams. The +`hadron` CLI runs it to find the GitHub issues no task of the team tracks yet, +and to mark the issues a task claims. Hadron itself never calls GitHub: the +adapter runs on the team's host with the team's own GitHub credential. + +The adapter implements the public, versioned intake adapter contract +(`cor:agt:120:04` in the Hadron specs), contract version **1**, in the +invocation format of the hadron CLI's adapter runner +([hadron-cli#1961](https://github.com/hadron-memory/hadron-cli/issues/1961)). + +## Install + +```sh +go install github.com/hadron-memory/hadron-task-adapter-github/cmd/hadron-task-adapter-github@latest +``` + +It needs a `hadron` CLI that has `team task find-untracked --adapter` +(hadron-cli#1961). + +## Use + +```sh +export GITHUB_TOKEN=… # the team's own GitHub token, never a Hadron one +export TASK_ADAPTER_GITHUB_CONFIG=~/.config/hadron-task-adapter-github/config.json + +hadron team task find-untracked --adapter hadron-task-adapter-github # list +hadron team task find-untracked --adapter hadron-task-adapter-github --track # claim and mark +``` + +`HADRON_INTAKE_ADAPTER=hadron-task-adapter-github` saves passing `--adapter`. + +You can also call the adapter directly to try a configuration: + +```sh +echo '{"contractVersion":1}' | hadron-task-adapter-github check +echo '{"contractVersion":1,"limit":5}' | hadron-task-adapter-github list-untracked +``` + +## Configuration + +The configuration is a JSON file, read from `$TASK_ADAPTER_GITHUB_CONFIG`, or +by default from `hadron-task-adapter-github/config.json` under the user +configuration directory (`~/.config` on Linux, `~/Library/Application Support` +on macOS). It holds the team's label model and no credential. **Keep it out of +this repository**, and out of any public one: it names the team's repositories, +labels and workers. [`config.example.json`](config.example.json) shows every +key. + +| Key | Meaning | +|---|---| +| `repositories` | `"owner/name"`, 1 to 20. Their **open issues** are the intake (pull requests are not). | +| `readyLabel` | The label that marks an issue ready for intake. | +| `ready` | `only` (list only ready issues; the default when `readyLabel` is set), `exclude`, or `any` (the default without one). | +| `excludeLabels` | An issue carrying any of these is never listed. | +| `teams` | Maps the CLI's `--for X` to a team: `{"for": ["Name", ""], "label": "team-x"}` lists the issues carrying `team-x`; `{"for": [...], "noTeam": true}` lists the issues carrying no team's label. A `--for` that no team maps is refused. Without `--for`, the list is not narrowed by team. | +| `trackedLabel` | The adapter's mark. Default `hadron-tracked`. | +| `comment` | `true` also posts a comment on mark naming the task (and its portal link, as the server printed it) and the worker. Off by default: on a public repository it publishes the team's worker names. | +| `tokenEnv` | The environment variable holding the token. Default: `GITHUB_TOKEN`, then `GH_TOKEN`. | +| `apiUrl`, `graphqlUrl`, `webHost` | For GitHub Enterprise Server: `https://HOST/api/v3`, `https://HOST/api/graphql`, `HOST`. Default github.com. Only `https` is accepted (plain `http` only to the loopback interface). | + +Labels are compared without regard to case. Unknown keys are refused, so a +misspelt key fails loudly instead of widening the intake. + +### The credential + +The adapter reads the team's GitHub token from the environment. It is sent only +in the `Authorization` header to the configured API, and never printed: error +text from GitHub is scrubbed of it. The hadron CLI never passes its own +`HADRON_*` credentials to an adapter, so a `HADRON_` variable cannot be the +token. + +A fine-grained token needs, on each configured repository: **Issues: read and +write** (to read issues and to add or remove the mark) and **Metadata: read**. + +Create the `trackedLabel` in each repository before the first claim +(`gh label create hadron-tracked -R owner/name`). `check` reports a repository +where it is missing. + +## The calls + +Every call is `hadron-task-adapter-github `, one argument and no shell. +The request is one JSON object on stdin, always with `"contractVersion": 1`; +the answer is one JSON object on stdout and exit 0. A refusal is a non-zero +exit, a one-line reason on stderr and nothing on stdout. + +| Call | Request | Answer | +|---|---|---| +| `describe` | (nothing else) | `name`, `version`, `contractVersion` (1), `calls`, `filters` (`["for"]`), `order` (`created-asc`). Answered whatever version the caller speaks. | +| `list-untracked` | `limit` (1 to 100, default 20), `cursor`, `for` | `items`: `[{externalId, title}]`; `nextCursor`, or `null` at the end of the list. | +| `mark-tracked` | `externalId`, `task` {`id`, `handle`, `portalUrl`}, `worker` {`id`, `name`, `role`, `model`} | `{"marked": true, …}` | +| `untrack` | `externalId` | `{"untracked": true, …}`. An issue with no mark is not an error. | +| `get` | `externalId` | `item`: `externalId` (as asked), `title`, `body`, `state` (`open`/`closed`), `url` (GitHub's canonical URL now), `tracked`. | +| `normalize` (optional) | `ref`: an issue URL, `owner/name#N`, or `#N` with one repository configured | `externalId`: GitHub's canonical issue URL. | +| `check` (optional) | (nothing else) | `ok`, and `checks`: the configuration, the credential, and for each repository that it is readable and has the `trackedLabel`. Always exit 0. | + +The optional calls `report` and `changed-since` are not answered yet. + +- **The external id** is the issue's canonical URL exactly as GitHub prints it, + for example `https://github.com/hadron-memory/hadron-server/issues/4084`: + one spelling for one issue, every time. The CLI writes it as given, and hands + the same string back to `mark-tracked`, `get` and `untrack`, which accept + only that shape and only for a configured repository. +- **The list's order** is oldest first across all repositories, then + repository, then issue number. +- **The cursor** is opaque. It records, for each repository, GitHub's own + position, and the query it belongs to: a cursor from another `--for` or from + before the configuration changed is refused, not resumed somewhere wrong. The + set of open issues does not change when an issue is marked (the mark is a + label, and filtering happens in the adapter), so a cursor taken before others + claimed still resumes at the right place and skips nothing. +- **The mark** is the `trackedLabel`, and optionally a comment. It never makes + or decides a claim: the claim is the CLI's task create. A second mark of the + same issue (after a reassignment) is an ordinary call, never a refusal. Once + the label is on, the call succeeds: a comment that then fails is answered as + `"commented": false` with a `commentError`, not as a refusal, since the issue + is marked and no longer lists. +- **Never partial.** A GitHub error, a rate limit, or an answer the adapter + does not understand refuses the whole call; a list is never cut short and + presented as whole. Labels past GitHub's first page of 100 are read too, + since they decide the filters. +- **Labels never reach Hadron.** No answer carries an issue's labels. + +### Exit codes + +| Code | Meaning | +|---|---| +| 0 | answered | +| 1 | GitHub refused, failed, or answered something unusable | +| 2 | the request: an unknown call, not one JSON object, another contract version, a bad argument or cursor | +| 3 | the configuration or the credential | + +The hadron CLI reads any non-zero exit as the adapter's refusal. + +## Development + +```sh +go test -race ./... # includes the conformance suite +golangci-lint run # the CI lint, gofmt included +``` + +[`conformance/`](conformance) builds the adapter and drives it the way the +hadron CLI's runner does, against a fake GitHub +([`internal/fakegithub`](internal/fakegithub)), checking every answer against +the runner's rules. Those rules are copied from hadron-cli (its runner package +is internal to the CLI module), and `conformance/runner_rules.go` names the +hadron-cli revision they were copied from. When the runner changes a bound, +change it there too. + +The design, and the decisions it rests on, is in [`docs/design.md`](docs/design.md). + +## License + +MIT, as hadron-cli. diff --git a/cmd/hadron-task-adapter-github/main.go b/cmd/hadron-task-adapter-github/main.go new file mode 100644 index 0000000..dbcf2a3 --- /dev/null +++ b/cmd/hadron-task-adapter-github/main.go @@ -0,0 +1,27 @@ +// Command hadron-task-adapter-github is the GitHub intake adapter for Hadron +// teams: the hadron CLI runs it to list a team's GitHub issues that no task +// tracks yet, and to mark the ones a task claims (cor:agt:120:04). See the +// README for the calls, the configuration and the credential. +package main + +import ( + "context" + "os" + "os/signal" + "syscall" + + "github.com/hadron-memory/hadron-task-adapter-github/internal/adapter" +) + +func main() { + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + code := adapter.Run(ctx, adapter.Env{ + Args: os.Args[1:], + Stdin: os.Stdin, + Stdout: os.Stdout, + Stderr: os.Stderr, + Getenv: os.Getenv, + }) + stop() + os.Exit(code) +} diff --git a/config.example.json b/config.example.json new file mode 100644 index 0000000..8f89c12 --- /dev/null +++ b/config.example.json @@ -0,0 +1,12 @@ +{ + "repositories": ["your-org/your-repo", "your-org/another-repo"], + "readyLabel": "ready", + "ready": "only", + "excludeLabels": ["epic", "wontfix"], + "teams": [ + { "for": ["WorkerName", "hrn:worker:example.com:your-team-app:workername"], "label": "team-a" }, + { "for": ["AnotherWorker"], "noTeam": true } + ], + "trackedLabel": "hadron-tracked", + "comment": false +} diff --git a/conformance/conformance_test.go b/conformance/conformance_test.go new file mode 100644 index 0000000..94b1f39 --- /dev/null +++ b/conformance/conformance_test.go @@ -0,0 +1,672 @@ +package conformance + +import ( + "bytes" + "encoding/json" + "fmt" + "os" + "os/exec" + "path/filepath" + "regexp" + "runtime" + "strings" + "testing" + "time" + + "github.com/hadron-memory/hadron-task-adapter-github/internal/fakegithub" +) + +// The suite runs the BUILT adapter the way the hadron-cli runner does: +// ` `, no shell, one JSON object on stdin carrying +// contractVersion, the answer one JSON object on stdout with exit 0. + +const token = "ghp_FAKEconformanceTOKEN0000000000000000" + +var bin string + +func TestMain(m *testing.M) { + dir, err := os.MkdirTemp("", "adapter-conformance-") + if err != nil { + panic(err) + } + bin = filepath.Join(dir, "hadron-task-adapter-github") + if runtime.GOOS == "windows" { + bin += ".exe" + } + build := exec.Command("go", "build", "-o", bin, "../cmd/hadron-task-adapter-github") + build.Stdout, build.Stderr = os.Stderr, os.Stderr + if err := build.Run(); err != nil { + fmt.Fprintln(os.Stderr, "building the adapter failed:", err) + os.Exit(1) + } + code := m.Run() + _ = os.RemoveAll(dir) + os.Exit(code) +} + +type env struct { + t *testing.T + gh *fakegithub.Server + config string + vars []string +} + +func newEnv(t *testing.T, cfg map[string]any) *env { + t.Helper() + gh := fakegithub.New(token) + t.Cleanup(gh.Close) + cfg["apiUrl"] = gh.URL + b, err := json.Marshal(cfg) + if err != nil { + t.Fatal(err) + } + p := filepath.Join(t.TempDir(), "config.json") + if err := os.WriteFile(p, b, 0o600); err != nil { + t.Fatal(err) + } + return &env{t: t, gh: gh, config: p, vars: []string{"GITHUB_TOKEN=" + token}} +} + +type result struct { + code int + stdout, stderr []byte +} + +// call runs one adapter call with the runner's request shape. +func (e *env) call(name string, req map[string]any) result { + e.t.Helper() + body := map[string]any{"contractVersion": ContractVersion} + for k, v := range req { + body[k] = v + } + stdin, _ := json.Marshal(body) + return e.raw([]string{name}, stdin) +} + +func (e *env) raw(args []string, stdin []byte) result { + e.t.Helper() + cmd := exec.Command(bin, args...) + cmd.Stdin = bytes.NewReader(stdin) + cmd.Env = append([]string{"PATH=" + os.Getenv("PATH"), "HOME=" + e.t.TempDir(), "TASK_ADAPTER_GITHUB_CONFIG=" + e.config}, e.vars...) + var out, errb bytes.Buffer + cmd.Stdout, cmd.Stderr = &out, &errb + err := cmd.Run() + code := 0 + if ee, ok := err.(*exec.ExitError); ok { + code = ee.ExitCode() + } else if err != nil { + e.t.Fatal(err) + } + return result{code: code, stdout: out.Bytes(), stderr: errb.Bytes()} +} + +func (e *env) ok(name string, req map[string]any, out any) { + e.t.Helper() + r := e.call(name, req) + if r.code != 0 { + e.t.Fatalf("%s exited %d: %s", name, r.code, r.stderr) + } + if err := OneObject(r.stdout, out); err != nil { + e.t.Fatalf("%s: %v", name, err) + } + e.noToken(r) +} + +func (e *env) noToken(r result) { + e.t.Helper() + // A fragment counts: a message cut short before it was scrubbed would + // print the credential's first characters (LOCAL delta at c6b55d29). Eight + // runes is the fragment the adapter redacts anywhere. + frag := []byte(token[:8]) + if bytes.Contains(r.stdout, frag) || bytes.Contains(r.stderr, frag) { + e.t.Fatalf("the GitHub credential (or a fragment of it) was printed:\nstdout %s\nstderr %s", r.stdout, r.stderr) + } +} + +// walk pages list-untracked as the runner's Walk does, applying its checks: +// a page bound, no repeated cursor, and an item seen once is not offered +// again. between runs after each page, before the next is asked for. +func (e *env) walk(forWorker string, limit int, between func([]Item)) []Item { + e.t.Helper() + seen := map[string]bool{"": true} + got := []Item{} + cursor := "" + for pages := 0; ; pages++ { + if pages >= MaxPages { + e.t.Fatalf("the list did not end within %d pages", MaxPages) + } + req := map[string]any{"limit": limit} + if cursor != "" { + req["cursor"] = cursor + } + if forWorker != "" { + req["for"] = forWorker + } + var p Page + e.ok("list-untracked", req, &p) + if err := CheckPage(p); err != nil { + e.t.Fatal(err) + } + if len(p.Items) > limit { + e.t.Fatalf("asked for %d, got %d", limit, len(p.Items)) + } + got = append(got, p.Items...) + if between != nil { + between(p.Items) + } + if p.NextCursor == nil { + return got + } + if seen[*p.NextCursor] { + e.t.Fatalf("the adapter repeated a cursor: %q", *p.NextCursor) + } + seen[*p.NextCursor] = true + cursor = *p.NextCursor + } +} + +func ids(items []Item) []string { + out := []string{} + for _, it := range items { + out = append(out, it.ExternalID) + } + return out +} + +func day(n int) time.Time { return time.Date(2026, 11, n, 12, 0, 0, 0, time.UTC) } + +func TestDescribeConforms(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + var d Describe + e.ok("describe", nil, &d) + if err := CheckDescribe(d); err != nil { + t.Fatal(err) + } +} + +// describe answers even with no configuration and no credential: the runner +// asks it first, to check the contract version, before anything else. +func TestDescribeNeedsNoConfigOrCredential(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.config = filepath.Join(t.TempDir(), "missing.json") + e.vars = nil + var d Describe + e.ok("describe", nil, &d) + if err := CheckDescribe(d); err != nil { + t.Fatal(err) + } +} + +// The walk lists every eligible open issue of every repository exactly once, +// oldest first across repositories (then repository, then number), and +// leaves out excluded, not-ready and already-marked issues. +func TestWalkListsEveryEligibleIssueOnceOldestFirst(t *testing.T) { + e := newEnv(t, map[string]any{ + "repositories": []string{"acme/app", "Acme/Lib"}, + "readyLabel": "cleared", + "excludeLabels": []string{"epic"}, + }) + e.gh.AddRepo("acme/app", + fakegithub.Issue{Number: 1, Title: "app one", CreatedAt: day(1), Labels: []string{"Cleared"}}, + fakegithub.Issue{Number: 2, Title: "not ready", CreatedAt: day(2)}, + fakegithub.Issue{Number: 3, Title: "an epic", CreatedAt: day(3), Labels: []string{"cleared", "EPIC"}}, + fakegithub.Issue{Number: 4, Title: "already marked", CreatedAt: day(4), Labels: []string{"cleared", "hadron-tracked"}}, + fakegithub.Issue{Number: 5, Title: "closed", CreatedAt: day(5), State: "CLOSED", Labels: []string{"cleared"}}, + fakegithub.Issue{Number: 6, Title: "app six", CreatedAt: day(8), Labels: []string{"cleared"}}, + ) + e.gh.AddRepo("Acme/Lib", + fakegithub.Issue{Number: 9, Title: "lib nine", CreatedAt: day(2), Labels: []string{"cleared"}}, + fakegithub.Issue{Number: 7, Title: "lib seven", CreatedAt: day(6), Labels: []string{"cleared"}}, + ) + for _, limit := range []int{1, 2, 100} { + got := ids(e.walk("", limit, nil)) + want := []string{ + e.gh.IssueURL("acme/app", 1), e.gh.IssueURL("Acme/Lib", 9), e.gh.IssueURL("Acme/Lib", 7), e.gh.IssueURL("acme/app", 6), + } + if strings.Join(got, " ") != strings.Join(want, " ") { + t.Fatalf("limit %d:\n got %v\nwant %v", limit, got, want) + } + } + // The external id is GitHub's own canonical URL, in GitHub's spelling. + if got := e.gh.IssueURL("Acme/Lib", 9); got != "https://github.com/Acme/Lib/issues/9" { + t.Fatalf("fixture: %s", got) + } +} + +// The set shrinks while others claim: items marked tracked between pages +// must not make the walk skip anything that is still untracked. +func TestMarksBetweenPagesSkipNothing(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + issues := []fakegithub.Issue{} + for i := 1; i <= 7; i++ { + issues = append(issues, fakegithub.Issue{Number: i, Title: fmt.Sprint("t", i), CreatedAt: day(i)}) + } + e.gh.AddRepo("acme/app", issues...) + got := e.walk("", 2, func(page []Item) { + for _, it := range page { + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": it.ExternalID, "task": map[string]any{"id": "t-" + it.ExternalID}, "worker": map[string]any{"name": "W"}}, &ans) + } + }) + if len(got) != 7 { + t.Fatalf("a walk with marks between pages listed %d of 7: %v", len(got), ids(got)) + } + if left := e.walk("", 100, nil); len(left) != 0 { + t.Fatalf("marked items are listed again: %v", ids(left)) + } +} + +func TestMarkThenUntrackRoundTrip(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "trackedLabel": "in-hadron"}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1), Labels: []string{"bug"}}) + id := e.gh.IssueURL("acme/app", 4) + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": id, + "task": map[string]any{"id": "01abc", "handle": "AT1.2", "portalUrl": "https://hadronmemory.com/app/u/x"}, + "worker": map[string]any{"id": "w1", "name": "Jonas", "role": "cli-engineer", "model": "m"}}, &ans) + if l := e.gh.Labels("acme/app", 4); strings.Join(l, ",") != "bug,in-hadron" { + t.Fatalf("labels after mark: %v", l) + } + if len(e.gh.Comments) != 0 { + t.Fatalf("a comment was posted without comment: true in the config: %v", e.gh.Comments) + } + // A second mark (a re-mark after a reassignment) is not refused: the + // mark never decides a claim. + e.ok("mark-tracked", map[string]any{"externalId": id, "task": map[string]any{"id": "01abc"}, "worker": map[string]any{"name": "Other"}}, &ans) + if got := e.walk("", 20, nil); len(got) != 0 { + t.Fatalf("a marked item is listed: %v", ids(got)) + } + e.ok("untrack", map[string]any{"externalId": id}, &ans) + if l := e.gh.Labels("acme/app", 4); strings.Join(l, ",") != "bug" { + t.Fatalf("labels after untrack: %v", l) + } + // untrack of an item that carries no mark is not an error. + e.ok("untrack", map[string]any{"externalId": id}, &ans) + if got := ids(e.walk("", 20, nil)); len(got) != 1 || got[0] != id { + t.Fatalf("an untracked item is listed again: %v", got) + } +} + +func TestMarkCommentIsOptInAndCarriesTheServersURL(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "comment": true}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": e.gh.IssueURL("acme/app", 4), + "task": map[string]any{"id": "01abc", "handle": "AT1.2", "portalUrl": "https://hadronmemory.com/app/u/hrn:agenttask:x"}, + "worker": map[string]any{"name": "Jonas\n@everyone", "role": "cli-engineer"}}, &ans) + if len(e.gh.Comments) != 1 { + t.Fatalf("comments: %v", e.gh.Comments) + } + c := e.gh.Comments[0].Body + if !strings.Contains(c, "https://hadronmemory.com/app/u/hrn:agenttask:x") || !strings.Contains(c, "AT1.2") { + t.Fatalf("comment does not name the task as the server printed it: %q", c) + } + // Text from Hadron is quoted as code, on one line, so a name cannot + // mention anyone or break the comment's layout. + if !strings.Contains(c, "`Jonas @everyone`") || strings.Contains(c, "Jonas\n") { + t.Fatalf("worker text reached the comment unneutralised: %q", c) + } +} + +// The label is the mark; the comment is decoration. A comment that fails +// after the label landed must not turn the call into a refusal: the runner +// would read the issue as unmarked while it no longer lists. +func TestMarkCommentFailureAfterTheLabelStillAnswersMarked(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "comment": true}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) + e.gh.FailComments(403) + e.gh.EchoInErrors(token) + var ans map[string]any + e.ok("mark-tracked", map[string]any{"externalId": e.gh.IssueURL("acme/app", 4), + "task": map[string]any{"id": "01abc"}, "worker": map[string]any{"name": "W"}}, &ans) + if ans["marked"] != true || ans["commented"] != false { + t.Fatalf("answer after a failed comment: %v", ans) + } + if msg, _ := ans["commentError"].(string); msg == "" || strings.Contains(msg, token) { + t.Fatalf("commentError missing or unscrubbed: %v", ans) + } + if l := e.gh.Labels("acme/app", 4); strings.Join(l, ",") != "hadron-tracked" { + t.Fatalf("labels after mark: %v", l) + } +} + +func TestGetAndNormalize(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("Acme/App", fakegithub.Issue{Number: 12, Title: "the title", Body: "the body", CreatedAt: day(1), Labels: []string{"hadron-tracked"}}) + id := e.gh.IssueURL("acme/app", 12) + var got struct { + Item struct { + ExternalID, Title, Body, State, URL string + Tracked bool + } + } + e.ok("get", map[string]any{"externalId": id}, &got) + if got.Item.ExternalID != id || got.Item.Title != "the title" || got.Item.Body != "the body" || got.Item.State != "open" || got.Item.URL != id || !got.Item.Tracked { + t.Fatalf("get: %+v", got.Item) + } + for _, ref := range []string{"acme/app#12", "ACME/APP#12", "https://github.com/acme/app/issues/12/", "#12"} { + var n struct{ ExternalID string } + e.ok("normalize", map[string]any{"ref": ref}, &n) + if n.ExternalID != id { + t.Fatalf("normalize %q = %q, want GitHub's canonical %q", ref, n.ExternalID, id) + } + } +} + +func TestForSelectsTheMappedTeam(t *testing.T) { + e := newEnv(t, map[string]any{ + "repositories": []string{"acme/app"}, + "teams": []map[string]any{ + {"for": []string{"Ada", "hrn:worker:example.com:team:ada"}, "label": "team-ada"}, + {"for": []string{"Xan"}, "label": "team-xan"}, + {"for": []string{"Bo"}, "noTeam": true}, + }, + }) + e.gh.AddRepo("acme/app", + fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1), Labels: []string{"team-ada"}}, + fakegithub.Issue{Number: 2, Title: "x", CreatedAt: day(2), Labels: []string{"Team-Xan"}}, + fakegithub.Issue{Number: 3, Title: "none", CreatedAt: day(3), Labels: []string{"bug"}}, + ) + cases := map[string][]string{ + "Ada": {e.gh.IssueURL("acme/app", 1)}, + "ada": {e.gh.IssueURL("acme/app", 1)}, + "hrn:worker:example.com:team:ada": {e.gh.IssueURL("acme/app", 1)}, + "Xan": {e.gh.IssueURL("acme/app", 2)}, + "Bo": {e.gh.IssueURL("acme/app", 3)}, + "": {e.gh.IssueURL("acme/app", 1), e.gh.IssueURL("acme/app", 2), e.gh.IssueURL("acme/app", 3)}, + } + for who, want := range cases { + if got := ids(e.walk(who, 20, nil)); strings.Join(got, " ") != strings.Join(want, " ") { + t.Fatalf("for %q: got %v want %v", who, got, want) + } + } + r := e.call("list-untracked", map[string]any{"limit": 20, "for": "Nobody"}) + if r.code == 0 { + t.Fatalf("an unmapped --for listed instead of refusing: %s", r.stdout) + } +} + +// Labels past the first page of 100 are still read: they decide the filters. +func TestLabelsPastOnePageDecideTheFilters(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "excludeLabels": []string{"wontfix"}}) + many := []string{} + for i := 0; i < 130; i++ { + many = append(many, fmt.Sprint("l", i)) + } + e.gh.AddRepo("acme/app", + fakegithub.Issue{Number: 1, Title: "excluded late", CreatedAt: day(1), Labels: append(append([]string{}, many...), "wontfix")}, + fakegithub.Issue{Number: 2, Title: "fine", CreatedAt: day(2), Labels: many}, + ) + if got := ids(e.walk("", 20, nil)); len(got) != 1 || got[0] != e.gh.IssueURL("acme/app", 2) { + t.Fatalf("got %v", got) + } +} + +// A tracker failure refuses the call: never a partial list presented as whole. +func TestTrackerFailureRefusesTheCall(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app", "acme/lib"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.AddRepo("acme/lib", fakegithub.Issue{Number: 1, Title: "b", CreatedAt: day(2)}) + e.gh.Fail("acme/lib", 502) + e.gh.EchoInErrors(token) + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("a failing repository still produced an answer: %s", r.stdout) + } + if len(bytes.TrimSpace(r.stdout)) != 0 { + t.Fatalf("a refused call wrote stdout: %s", r.stdout) + } + e.noToken(r) +} + +func TestCredentialIsTheTeamsNeverHadrons(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.vars = []string{"HADRON_TOKEN=" + token} + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("listed with no GitHub credential (only a Hadron one): %s", r.stdout) + } + if n := len(e.gh.Requests); n != 0 { + t.Fatalf("GitHub was called without the team's credential: %v", e.gh.Requests) + } + e.noToken(r) + // A credential named by tokenEnv is used. + e2 := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "tokenEnv": "ACME_GH"}) + e2.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e2.vars = []string{"ACME_GH=" + token} + if got := e2.walk("", 20, nil); len(got) != 1 { + t.Fatalf("tokenEnv credential: %v", ids(got)) + } +} + +func TestRequestDisciplineIsRefused(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + // Every repository and issue the cases name exists and is readable, so + // each refusal is the adapter's own, not GitHub's. + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.AddRepo("other/repo", fakegithub.Issue{Number: 1, Title: "b", CreatedAt: day(1)}) + var sane Page + e.ok("list-untracked", map[string]any{"limit": 20}, &sane) + var got map[string]any + e.ok("get", map[string]any{"externalId": e.gh.IssueURL("acme/app", 1)}, &got) + cases := map[string]struct { + args []string + stdin string + }{ + "unknown call": {[]string{"list-everything"}, `{"contractVersion":1}`}, + "no call": {nil, `{"contractVersion":1}`}, + "two arguments": {[]string{"list-untracked", "--all"}, `{"contractVersion":1}`}, + "other version": {[]string{"list-untracked"}, `{"contractVersion":2}`}, + "no version": {[]string{"list-untracked"}, `{}`}, + "not json": {[]string{"list-untracked"}, `hello`}, + "two documents": {[]string{"list-untracked"}, `{"contractVersion":1}{"contractVersion":1}`}, + "limit out of rng": {[]string{"list-untracked"}, `{"contractVersion":1,"limit":101}`}, + "foreign repo mark": {[]string{"mark-tracked"}, `{"contractVersion":1,"externalId":"https://github.com/other/repo/issues/1","task":{"id":"t"},"worker":{}}`}, + "not an issue url": {[]string{"get"}, `{"contractVersion":1,"externalId":"https://github.com/acme/app/pull/1"}`}, + "forged cursor": {[]string{"list-untracked"}, `{"contractVersion":1,"cursor":"v1.bm90IGEgY3Vyc29y"}`}, + } + for name, c := range cases { + t.Run(name, func(t *testing.T) { + r := e.raw(c.args, []byte(c.stdin)) + if r.code == 0 { + t.Fatalf("accepted: %s", r.stdout) + } + if len(bytes.TrimSpace(r.stdout)) != 0 { + t.Fatalf("a refusal wrote stdout: %s", r.stdout) + } + if len(r.stderr) == 0 { + t.Fatal("a refusal gave no reason on stderr") + } + }) + } +} + +// A cursor carries its query: one issued for another --for, or before the +// configuration changed, is refused rather than resumed somewhere wrong. +func TestCursorIsBoundToItsQuery(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}, "teams": []map[string]any{{"for": []string{"Ada"}, "label": "a"}, {"for": []string{"Xan"}, "label": "x"}}}) + for i := 1; i <= 3; i++ { + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: i, Title: "t", CreatedAt: day(i), Labels: []string{"a", "x"}}) + } + var p Page + e.ok("list-untracked", map[string]any{"limit": 1, "for": "Ada"}, &p) + if p.NextCursor == nil { + t.Fatal("no cursor") + } + if r := e.call("list-untracked", map[string]any{"limit": 1, "for": "Xan", "cursor": *p.NextCursor}); r.code == 0 { + t.Fatalf("a cursor for Ada was resumed for Xan: %s", r.stdout) + } +} + +// The cursor stays inside the runner's bound with the most repositories the +// configuration allows, every one of them part-way through, with GitHub +// positions longer than any seen (their length is not promised). +func TestCursorFitsTheRunnersBoundAtMaxRepositories(t *testing.T) { + repos := []string{} + for i := 0; i < 20; i++ { + repos = append(repos, fmt.Sprintf("a-rather-long-organisation-name/a-rather-long-repository-name-%02d", i)) + } + e := newEnv(t, map[string]any{"repositories": repos}) + e.gh.PadCursors(129) + for i, r := range repos { + e.gh.AddRepo(r, + fakegithub.Issue{Number: 100000 + i, Title: "t", CreatedAt: day(1).Add(time.Duration(i) * time.Minute)}, + fakegithub.Issue{Number: 200000 + i, Title: "t", CreatedAt: day(20)}, + ) + } + var p Page + e.ok("list-untracked", map[string]any{"limit": 20}, &p) + if p.NextCursor == nil || len(p.Items) != 20 { + t.Fatalf("items %d cursor %v", len(p.Items), p.NextCursor) + } + if err := CheckPage(p); err != nil { + t.Fatal(err) + } + if got := len(e.walk("", 100, nil)); got != 40 { + t.Fatalf("walk: %d of 40", got) + } +} + +// Positions too long to fit refuse the call: a page is never answered with +// a cursor the runner would refuse. +func TestACursorThatCannotFitIsARefusalNotAnAnswer(t *testing.T) { + repos := []string{} + for i := 0; i < 20; i++ { + repos = append(repos, fmt.Sprintf("acme/r%02d", i)) + } + e := newEnv(t, map[string]any{"repositories": repos}) + e.gh.PadCursors(400) + for i, r := range repos { + e.gh.AddRepo(r, + fakegithub.Issue{Number: 1, Title: "t", CreatedAt: day(1).Add(time.Duration(i) * time.Minute)}, + fakegithub.Issue{Number: 2, Title: "t", CreatedAt: day(20)}, + ) + } + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + var p Page + if err := OneObject(r.stdout, &p); err == nil && CheckPage(p) == nil { + return // fitted after all: fine + } + t.Fatalf("answered with a cursor the runner refuses: %d bytes", len(r.stdout)) + } + if len(bytes.TrimSpace(r.stdout)) != 0 { + t.Fatalf("a refusal wrote stdout") + } +} + +// Text GitHub returns is never repeated with the credential in it: not +// only GitHub's error messages, but data the adapter refuses. +func TestARefusedIssueURLDoesNotEchoTheCredential(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.SuffixURLs("?echo=" + token) + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("a malformed issue URL was listed: %s", r.stdout) + } + e.noToken(r) +} + +// Untrusted text is cut to a bounded length in a refusal. The credential is +// scrubbed before the cut, so a cut that lands inside it leaks no prefix. +func TestACredentialCutShortInARefusalLeaksNoFragment(t *testing.T) { + // Every pad from 0 to 130 puts the cut at every offset inside the token. + for pad := 0; pad <= 130; pad++ { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 1, Title: "a", CreatedAt: day(1)}) + e.gh.SuffixURLs("?pad=" + strings.Repeat("x", pad) + "&echo=" + token) + r := e.call("list-untracked", map[string]any{"limit": 20}) + if r.code == 0 { + t.Fatalf("pad %d: a malformed issue URL was listed: %s", pad, r.stdout) + } + e.noToken(r) + // The same for an id the runner hands back. + bad := "https://github.com/acme/app/pull/1?pad=" + strings.Repeat("x", pad) + "&echo=" + token + r = e.call("get", map[string]any{"externalId": bad}) + if r.code == 0 { + t.Fatalf("pad %d: a pull URL was read as an issue: %s", pad, r.stdout) + } + e.noToken(r) + } +} + +// A request with anything after its one object is refused before any write. +func TestTrailingTextAfterTheRequestIsRefusedBeforeAnyWrite(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app", fakegithub.Issue{Number: 4, Title: "x", CreatedAt: day(1)}) + req := `{"contractVersion":1,"externalId":"` + e.gh.IssueURL("acme/app", 4) + `","task":{"id":"t"},"worker":{}}` + for _, suffix := range []string{"]", "}", " x", "{}", "null"} { + r := e.raw([]string{"mark-tracked"}, []byte(req+suffix)) + if r.code == 0 { + t.Fatalf("suffix %q accepted: %s", suffix, r.stdout) + } + if l := e.gh.Labels("acme/app", 4); len(l) != 0 { + t.Fatalf("suffix %q: the mark was written before the refusal: %v", suffix, l) + } + } +} + +func TestCheckReports(t *testing.T) { + e := newEnv(t, map[string]any{"repositories": []string{"acme/app"}}) + e.gh.AddRepo("acme/app") + type report struct { + OK bool + Checks []struct { + Name string + OK bool + Detail string + } + } + var c report + e.ok("check", nil, &c) + if c.OK { + t.Fatalf("check passed with the tracked label not defined in the repository: %+v", c) + } + e.gh.DefineLabel("acme/app", "Hadron-Tracked") + c = report{} + e.ok("check", nil, &c) + if !c.OK { + t.Fatalf("check failed on a sound setup: %+v", c) + } + e2 := newEnv(t, map[string]any{"repositories": []string{"acme/app", "acme/gone"}}) + e2.gh.AddRepo("acme/app") + e2.gh.DefineLabel("acme/app", "hadron-tracked") + c = report{} + e2.ok("check", nil, &c) + if c.OK { + t.Fatalf("check passed with an unreadable repository: %+v", c) + } + e.vars = nil + e.ok("check", nil, &c) + if c.OK || len(c.Checks) == 0 || c.Checks[0].OK { + t.Fatalf("check passed with no credential: %+v", c) + } +} + +// Nothing team-specific and no credential is committed to this public +// repository: no configuration file but the example, and nothing shaped like +// a GitHub token except this suite's own labelled fakes. +func TestRepositoryCarriesNoCredentialOrTeamConfig(t *testing.T) { + out, err := exec.Command("git", "-C", "..", "ls-files").Output() + if err != nil { + t.Skip("not a git checkout:", err) + } + tokenShape := regexp.MustCompile(`(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}`) + for _, f := range strings.Fields(string(out)) { + base := filepath.Base(f) + if strings.HasSuffix(base, ".json") && base != "config.example.json" { + t.Errorf("%s: a JSON file is committed; adapter configuration stays with the team", f) + } + b, err := os.ReadFile(filepath.Join("..", f)) + if err != nil { + t.Fatal(err) + } + for _, m := range tokenShape.FindAllString(string(b), -1) { + if !strings.Contains(m, "FAKE") { + t.Errorf("%s: something shaped like a GitHub token is committed", f) + } + } + } +} diff --git a/conformance/runner_rules.go b/conformance/runner_rules.go new file mode 100644 index 0000000..799e12b --- /dev/null +++ b/conformance/runner_rules.go @@ -0,0 +1,150 @@ +// Package conformance holds the hadron-cli intake runner's rules for an +// adapter's answers, and a suite that runs the built adapter against them. +// +// The rules are copied from hadron-cli at 585bd9d6 (internal/intake/intake.go, +// hadron-cli#1961, the invocation format of cor:agt:120:04), because that +// package is internal to the CLI module and cannot be imported. They are +// copied, not paraphrased: each constant names its source. When the CLI's +// runner changes a bound, change it here in the same breath and name the new +// revision in RunnerRevision. +package conformance + +import ( + "bytes" + "encoding/json" + "fmt" + "strings" + "unicode" + "unicode/utf8" +) + +// RunnerRevision is the hadron-cli commit whose runner these rules copy. +const RunnerRevision = "585bd9d6" + +// ContractVersion is the contract version the runner speaks (intake.ContractVersion). +const ContractVersion = 1 + +// Bounds, as in hadron-cli internal/intake/intake.go at RunnerRevision. +const ( + MaxOutputBytes = 1 << 20 // stdout of one call + MaxItemsPerPage = 100 + MaxPages = 50 + ServerExternalIDMax = 512 // code points + MaxExternalIDLen = 2048 + MaxCursorLen = 4096 + MaxTextLen = 1024 +) + +// CoreCalls are the calls every adapter answers (cor:agt:120:04, The Grammar). +var CoreCalls = []string{"describe", "list-untracked", "mark-tracked", "untrack", "get"} + +// Describe is what the runner reads from `describe`. +type Describe struct { + Name string `json:"name"` + ContractVersion int `json:"contractVersion"` + Calls []string `json:"calls"` + Filters []string `json:"filters"` + Order string `json:"order"` +} + +// Item and Page are what the runner reads from `list-untracked`. +type Item struct { + ExternalID string `json:"externalId"` + Title string `json:"title"` +} + +type Page struct { + Items []Item `json:"items"` + NextCursor *string `json:"nextCursor"` +} + +// OneObject applies the runner's checks on any answer: at most +// MaxOutputBytes, valid UTF-8, exactly one JSON object and nothing after it. +func OneObject(stdout []byte, out any) error { + if len(stdout) > MaxOutputBytes { + return fmt.Errorf("more than %d bytes on stdout", MaxOutputBytes) + } + raw := bytes.TrimSpace(stdout) + if len(raw) == 0 || raw[0] != '{' { + return fmt.Errorf("stdout is not one JSON object: %q", trunc(raw)) + } + if !utf8.Valid(raw) { + return fmt.Errorf("stdout is not valid UTF-8") + } + if err := json.Unmarshal(raw, out); err != nil { + return fmt.Errorf("stdout is not one well-formed JSON object: %v", err) + } + return nil +} + +// CheckDescribe applies the runner's describe checks, plus the contract's +// rule that every core call is answered. +func CheckDescribe(d Describe) error { + if d.ContractVersion != ContractVersion { + return fmt.Errorf("contractVersion %d, the runner speaks %d", d.ContractVersion, ContractVersion) + } + if strings.TrimSpace(d.Name) == "" || len(d.Name) > MaxTextLen { + return fmt.Errorf("name %q is empty or longer than %d bytes", d.Name, MaxTextLen) + } + for _, c := range CoreCalls { + found := false + for _, have := range d.Calls { + found = found || have == c + } + if !found { + return fmt.Errorf("describe.calls does not list the core call %q", c) + } + } + return nil +} + +// CheckPage applies the runner's per-page checks, and the external id's own +// checks (cor:agt:120:02: 1 to 512 characters, no whitespace, control or +// invisible format characters, no userinfo), which the server applies to the +// claim the runner writes. +func CheckPage(p Page) error { + if len(p.Items) > MaxItemsPerPage { + return fmt.Errorf("%d items in one page, more than %d", len(p.Items), MaxItemsPerPage) + } + for i, it := range p.Items { + if err := CheckExternalID(it.ExternalID); err != nil { + return fmt.Errorf("item %d: %v", i, err) + } + if len(it.Title) > MaxTextLen { + return fmt.Errorf("item %d: title longer than %d bytes", i, MaxTextLen) + } + } + if p.NextCursor != nil && len(*p.NextCursor) > MaxCursorLen { + return fmt.Errorf("nextCursor is %d bytes, more than %d", len(*p.NextCursor), MaxCursorLen) + } + return nil +} + +// CheckExternalID is the external id's checks. +func CheckExternalID(id string) error { + if id == "" { + return fmt.Errorf("no externalId") + } + if len(id) > MaxExternalIDLen || utf8.RuneCountInString(id) > ServerExternalIDMax { + return fmt.Errorf("externalId longer than %d characters", ServerExternalIDMax) + } + for _, r := range id { + if unicode.IsSpace(r) || unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return fmt.Errorf("externalId %q has whitespace, control or invisible format characters", id) + } + } + if scheme, rest, ok := strings.Cut(id, "://"); ok && scheme != "" { + host, _, _ := strings.Cut(rest, "/") + if strings.Contains(host, "@") { + return fmt.Errorf("externalId %q carries userinfo", id) + } + } + return nil +} + +func trunc(b []byte) string { + if len(b) > 80 { + return string(b[:80]) + "…" + } + return string(b) +} diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..cb9e5f3 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,121 @@ +# Design, as built + +[hadron-cli#1963](https://github.com/hadron-memory/hadron-cli/issues/1963): the +GitHub intake adapter, published in this public repository. + +Governing: `cor:agt:120` r10 (Task integrations: D2 the team's own credential, +D5 a public contract, D7 the label model in the adapter's configuration, D11 an +opaque cursor, D14 the mark never makes a claim), `cor:agt:120:04` (the intake +adapter contract), `cor:agt:120:02` (the external id and its checks). The +invocation format is the hadron CLI owner's, built in hadron-cli#1961 (merged +585bd9d6): `internal/intake` and `docs/plans/1961-intake-adapter-runner.md` +there. + +## Shape + +One Go executable with no dependencies beyond the standard library, so +`go install` is the whole installation. `cmd/` is a thin `main`; +`internal/adapter` is the protocol, the calls, the configuration and the +GitHub client; `internal/fakegithub` is the test stand-in; `conformance/` is +the suite against the runner's rules. + +GitHub is read through GraphQL: one query per repository page, issues in +creation order with their labels and per-issue cursors. Labels are written +through REST (add, remove), and REST also reads labels past GraphQL's first +page of 100. + +## Decisions taken here, and why + +**The mark is a label.** Removing a label is a clean `untrack`, the label is +visible on GitHub without reading comments, and it is what `list-untracked` +filters on. A comment naming the task and worker is opt-in (`comment: true`) +because on a public repository it publishes the team's worker names and links. +Hadron text in a comment is quoted as inline code on one line, so a name cannot +mention, link or reflow. The portal URL is linked only as the server printed +it, and only a plain https URL. Because the label alone is the mark, a comment +that fails after the label landed does not refuse the call: the answer says +`"commented": false` and carries the scrubbed `commentError`. Refusing would +tell the runner the mark failed while the issue is marked and no longer lists. + +**Filtering happens in the adapter, after GitHub's paging.** The GitHub list +is all open issues in creation order. The tracked label, the excluded labels, +the team and the ready label are applied to each issue as it is read. So a +mark (a label) never removes an issue from the sequence GitHub pages over, and +a cursor taken before others claimed still resumes at the right place. This is +the property `cor:agt:120:04` asks the opaque cursor to protect ("the set +shrinks while others claim"); `TestMarksBetweenPagesSkipNothing` pins it. Using +GitHub's search API with `-label:hadron-tracked` instead would page over a set +that shrinks between pages, and skip. + +**One order across repositories.** Oldest first, then repository, then number: +the order of today's server-side integration (cor:agt:120:03, D7), so a team +moving from it sees the same list. Each call merges the repositories' next +issues; the cursor keeps GitHub's cursor per repository (or `null` once one is +done), so nothing is re-read or skipped. + +**The cursor carries its query.** It embeds a fingerprint of the +configuration's filters, its repositories and `for`. A cursor resumed under a +different query is refused (exit 2), not silently resumed at a position that +means something else. With 20 repositories, the configuration's cap, and GitHub +positions up to about 140 bytes each (real ones are about 60), the cursor +stays inside the runner's 4096-byte bound (pinned with padded positions). A +call whose cursor would not fit is refused, never answered with a cursor the +runner would refuse. + +**Bounded work per call.** A call reads at most one GitHub page per repository +plus 20 more, then answers with the eligible issues it has and a cursor. A long +run of ineligible issues therefore costs reads, not a timeout. Every call +consumes at least one issue, so the cursor always moves and the runner never +sees a repeated cursor. + +**Never a partial answer.** Any GitHub error, a GraphQL `errors` entry, a rate +limit, an issue that lacks a field, or an empty page that still promises more +refuses the whole call. A list is never cut short and presented as whole. + +**The external id is GitHub's URL, checked.** Each listed id is the issue URL +GitHub printed, checked to be `https://///issues/` +for the repository and number it was read as, and against `cor:agt:120:02`'s +checks. The ids handed back (`mark-tracked`, `untrack`, `get`) are parsed +strictly to that shape and must name a configured repository, so the adapter +acts on nothing else. + +**`for` is mapped, or refused.** The runner passes `--for X` as written. The +team map lists, per team, the worker names and URNs it covers, compared without +regard to case. A `for` that no team maps is refused: silently listing every +team's issues for an unknown worker would hand work to the wrong team. Without +`for`, the list is not narrowed by team. + +**The credential.** The token comes from `GITHUB_TOKEN`, `GH_TOKEN` or the +variable `tokenEnv` names, never a `HADRON_` variable (the CLI strips those +from an adapter's environment, and `tokenEnv` refuses one). It goes only into +the `Authorization` header, to an https endpoint (plain http only to the +loopback interface, for a local fake or proxy). GitHub's own error text is +scrubbed of it before it is repeated. + +**`describe` needs nothing.** It answers without a configuration or a +credential, and whatever contract version the request names: it is how the +CLI learns the adapter's version before asking anything else. + +**Request shapes the runner does not yet send.** At 585bd9d6 the runner calls +`describe`, `list-untracked` and `mark-tracked`. `untrack` and `get` (core) and +`normalize` and `check` (optional) are answered here with the shapes the README +states: `{externalId}` for `untrack` and `get`, `{ref}` for `normalize`, nothing +for `check`. hadron-cli#1962 (reconcile and release) is the first caller of +`untrack` and `get`; if it settles another shape, this adapter follows it. + +## Conformance + +The runner's checks live in hadron-cli's `internal/intake`, which another +module cannot import. `conformance/runner_rules.go` copies them (the bounds, +one JSON object on stdout, the external id's checks, the walk's cursor rules) +and names the hadron-cli revision they come from. The suite builds the adapter +and runs it as the runner does, against `internal/fakegithub`. + +Exposing the runner's checks as an importable package in hadron-cli, so this +suite imports them instead of copying, is a hadron-cli change and is left for +a follow-up there. + +## Not built + +- `report` and `changed-since` (optional calls). +- A release pipeline (goreleaser, tags). `go install` works from a tag or `main`. diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..63aad72 --- /dev/null +++ b/go.mod @@ -0,0 +1,3 @@ +module github.com/hadron-memory/hadron-task-adapter-github + +go 1.26.11 diff --git a/internal/adapter/adapter.go b/internal/adapter/adapter.go new file mode 100644 index 0000000..aa7fa5c --- /dev/null +++ b/internal/adapter/adapter.go @@ -0,0 +1,239 @@ +// Package adapter is the GitHub intake adapter: the calls of the intake +// adapter contract (cor:agt:120:04) answered against GitHub issues, invoked +// the way the hadron-cli runner invokes an adapter (hadron-cli#1961): +// +// hadron-task-adapter-github +// +// with one JSON object on stdin, which always carries "contractVersion", and +// one JSON object on stdout with exit 0. Any refusal is a non-zero exit, a +// one-line reason on stderr, and nothing on stdout. +package adapter + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "time" +) + +// ContractVersion is the contract version this adapter speaks. +const ContractVersion = 1 + +// Name is the adapter's name in describe. +const Name = "hadron-task-adapter-github" + +// Version is the adapter's own version, set at build time. +var Version = "dev" + +// Exit codes. Any non-zero exit is a refusal to the runner; the codes only +// tell a person which kind. +const ( + ExitOK = 0 + ExitTracker = 1 // GitHub refused, failed or answered something unusable + ExitUsage = 2 // the request: unknown call, bad JSON, another contract version, a bad argument + ExitConfig = 3 // the configuration or the credential +) + +const ( + maxRequestBytes = 1 << 20 + callTimeout = 50 * time.Second // inside the runner's 60 s + defaultLimit = 20 +) + +// Calls lists every call this adapter answers (describe.calls). +var Calls = []string{"describe", "list-untracked", "mark-tracked", "untrack", "get", "normalize", "check"} + +type exitError struct { + code int + msg string +} + +func (e *exitError) Error() string { return e.msg } + +func usageErr(f string, a ...any) error { return &exitError{ExitUsage, fmt.Sprintf(f, a...)} } +func configErr(f string, a ...any) error { return &exitError{ExitConfig, fmt.Sprintf(f, a...)} } + +// Env is what a run sees of its process. +type Env struct { + Args []string // the arguments after the program name + Stdin io.Reader + Stdout io.Writer + Stderr io.Writer + Getenv func(string) string +} + +// Run answers one call and returns the process's exit code. +func Run(ctx context.Context, e Env) int { + ctx, cancel := context.WithTimeout(ctx, callTimeout) + defer cancel() + var token string + out, err := run(ctx, e, &token) + if err == nil { + b, merr := json.Marshal(out) + if merr == nil { + b = append(b, '\n') + if _, werr := e.Stdout.Write(b); werr == nil { + return ExitOK + } + } + err = &exitError{ExitTracker, "the answer could not be written"} + } + code := ExitTracker + var ee *exitError + if errors.As(err, &ee) { + code = ee.code + } + // Every refusal is scrubbed of the credential, whatever its source: + // GitHub's error text, or data GitHub returned that the adapter refuses. + fmt.Fprintf(e.Stderr, "%s: %s\n", Name, oneLine(redact(err.Error(), token), 600)) + return code +} + +func run(ctx context.Context, e Env, tokenOut *string) (any, error) { + if len(e.Args) != 1 { + return nil, usageErr("expected exactly one argument, the call (one of %v)", Calls) + } + call := e.Args[0] + known := false + for _, c := range Calls { + known = known || c == call + } + if !known { + return nil, usageErr("%q is not a call this adapter answers (one of %v)", oneLine(call, 40), Calls) + } + req, err := readRequest(e.Stdin) + if err != nil { + return nil, err + } + var version struct { + ContractVersion *int `json:"contractVersion"` + } + _ = json.Unmarshal(req, &version) + // describe answers whatever version the caller speaks: it is how the + // caller learns which one this adapter speaks. + if call == "describe" { + return describe(), nil + } + if version.ContractVersion == nil || *version.ContractVersion != ContractVersion { + got := "none" + if version.ContractVersion != nil { + got = fmt.Sprint(*version.ContractVersion) + } + return nil, usageErr("the request speaks contract version %s; this adapter speaks %d", got, ContractVersion) + } + if call == "check" { + return check(ctx, e.Getenv), nil + } + cfg, err := LoadConfig(e.Getenv) + if err != nil { + return nil, configErr("%v", err) + } + token, err := cfg.Token(e.Getenv) + if err != nil { + return nil, configErr("%v", err) + } + *tokenOut = token + s := &session{cfg: cfg, gh: newGitHub(cfg, token)} + switch call { + case "list-untracked": + return s.listUntracked(ctx, req) + case "mark-tracked": + return s.markTracked(ctx, req) + case "untrack": + return s.untrack(ctx, req) + case "get": + return s.get(ctx, req) + case "normalize": + return s.normalize(ctx, req) + } + return nil, usageErr("%q is not answered", call) +} + +// readRequest reads exactly one JSON object from stdin. +func readRequest(r io.Reader) (json.RawMessage, error) { + b, err := io.ReadAll(io.LimitReader(r, maxRequestBytes+1)) + if err != nil { + return nil, usageErr("the request could not be read") + } + if len(b) > maxRequestBytes { + return nil, usageErr("the request is larger than %d bytes", maxRequestBytes) + } + b = bytes.TrimSpace(b) + if len(b) == 0 || b[0] != '{' { + return nil, usageErr("the request is not one JSON object") + } + var raw json.RawMessage + dec := json.NewDecoder(bytes.NewReader(b)) + if err := dec.Decode(&raw); err != nil { + return nil, usageErr("the request is not one well-formed JSON object") + } + // More is not an end-of-input check: it reports false before a stray + // "]" or "}". Only io.EOF after the object proves nothing follows. + if _, err := dec.Token(); err != io.EOF { + return nil, usageErr("the request carries text after its JSON object") + } + return raw, nil +} + +func decode(req json.RawMessage, call string, v any) error { + if err := json.Unmarshal(req, v); err != nil { + return usageErr("the %s request has a field of the wrong type: %v", call, err) + } + return nil +} + +type describeAnswer struct { + Name string `json:"name"` + Version string `json:"version"` + ContractVersion int `json:"contractVersion"` + Calls []string `json:"calls"` + Filters []string `json:"filters"` + Order string `json:"order"` +} + +func describe() describeAnswer { + return describeAnswer{ + Name: Name, + Version: Version, + ContractVersion: ContractVersion, + Calls: Calls, + // `for` is the only filter a caller passes; the label model is the + // configuration's. + Filters: []string{"for"}, + Order: "created-asc", + } +} + +type session struct { + cfg *Config + gh *githubClient +} + +func (s *session) listUntracked(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + Limit *int `json:"limit"` + Cursor string `json:"cursor"` + For string `json:"for"` + } + if err := decode(req, "list-untracked", &r); err != nil { + return nil, err + } + limit := defaultLimit + if r.Limit != nil { + limit = *r.Limit + } + if limit < 1 || limit > 100 { + return nil, usageErr("limit %d is outside 1 to 100", limit) + } + items, next, err := (&lister{cfg: s.cfg, gh: s.gh}).list(ctx, r.Cursor, r.For, limit) + if err != nil { + return nil, err + } + return struct { + Items []listedItem `json:"items"` + NextCursor *string `json:"nextCursor"` + }{items, next}, nil +} diff --git a/internal/adapter/calls.go b/internal/adapter/calls.go new file mode 100644 index 0000000..76e3bd2 --- /dev/null +++ b/internal/adapter/calls.go @@ -0,0 +1,292 @@ +package adapter + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" +) + +// configuredIssue reads an external id the CLI hands back and checks it names +// an issue of a configured repository. The adapter acts only on the +// repositories its configuration lists. +func (s *session) configuredIssue(call, externalID string) (issueRef, error) { + if externalID == "" { + return issueRef{}, usageErr("%s needs an externalId", call) + } + ref, err := parseIssueURL(externalID, s.cfg.WebHost) + if err != nil { + return issueRef{}, usageErr("%s: %q: %v", call, s.gh.clip(externalID, 120), err) + } + if !s.cfg.hasRepo(ref.Owner, ref.Name) { + return issueRef{}, usageErr("%s: %s/%s is not a repository in the adapter's configuration", call, ref.Owner, ref.Name) + } + return ref, nil +} + +func issuePath(ref issueRef, rest string) string { + return fmt.Sprintf("/repos/%s/%s/issues/%d%s", escapePath(ref.Owner), escapePath(ref.Name), ref.Number, rest) +} + +type markRequest struct { + ExternalID string `json:"externalId"` + Task struct { + ID string `json:"id"` + Handle string `json:"handle"` + PortalURL string `json:"portalUrl"` + } `json:"task"` + Worker struct { + ID string `json:"id"` + Name string `json:"name"` + Role string `json:"role"` + Model string `json:"model"` + } `json:"worker"` +} + +// markTracked puts the tracked label on the issue, and when the +// configuration asks for it, a comment naming the task and the worker. It +// never refuses once the label is on: a failed comment is reported as +// commented:false with a commentError. It never refuses because the issue +// is already marked: the mark shows a claim, it never makes or decides one +// (cor:agt:120, D14). A re-mark after a reassignment is an ordinary call. +func (s *session) markTracked(ctx context.Context, req json.RawMessage) (any, error) { + var r markRequest + if err := decode(req, "mark-tracked", &r); err != nil { + return nil, err + } + ref, err := s.configuredIssue("mark-tracked", r.ExternalID) + if err != nil { + return nil, err + } + if r.Task.ID == "" { + return nil, usageErr("mark-tracked needs the task's id") + } + body := map[string][]string{"labels": {s.cfg.TrackedLabel}} + if _, err := s.gh.rest(ctx, http.MethodPost, issuePath(ref, "/labels"), body, nil, http.StatusOK); err != nil { + return nil, fmt.Errorf("labelling %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) + } + ans := map[string]any{"marked": true, "externalId": r.ExternalID, "label": s.cfg.TrackedLabel, "commented": false} + if s.cfg.Comment { + if _, err := s.gh.rest(ctx, http.MethodPost, issuePath(ref, "/comments"), map[string]string{"body": markComment(r)}, nil, http.StatusCreated); err != nil { + // The label is the mark, and it is on: the issue no longer + // lists. Refusing now would tell the runner the mark failed + // while the issue is in fact marked, stranding it outside + // intake. The comment is decoration, so its failure is + // reported in a successful answer, scrubbed like a refusal. + ans["commentError"] = s.gh.scrub(err.Error()) + return ans, nil + } + ans["commented"] = true + } + return ans, nil +} + +// code quotes text from Hadron as inline code on one line, so a name cannot +// mention anyone, link anywhere or change the comment's layout. +func code(s string) string { + s = strings.ReplaceAll(oneLine(s, 120), "`", "'") + if s == "" { + return "" + } + return "`" + s + "`" +} + +func markComment(r markRequest) string { + var b strings.Builder + b.WriteString("Tracked in Hadron") + task := r.Task.Handle + if task == "" { + task = r.Task.ID + } + fmt.Fprintf(&b, " as task %s", code(task)) + // The portal URL is the server's, passed as printed (cor:agt:120:04); + // the adapter builds none, and links only a plain https URL. + if u := r.Task.PortalURL; strings.HasPrefix(u, "https://") && checkExternalID(u) == nil && !strings.ContainsAny(u, "()[]<>`") { + fmt.Fprintf(&b, " (%s)", u) + } + if r.Worker.Name != "" { + fmt.Fprintf(&b, ", by %s", code(r.Worker.Name)) + if r.Worker.Role != "" { + fmt.Fprintf(&b, " (%s)", code(r.Worker.Role)) + } + } + b.WriteString(".") + return b.String() +} + +// untrack removes the tracked label. An issue that carries no mark is not an +// error: the outcome the caller wants already holds. +func (s *session) untrack(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + ExternalID string `json:"externalId"` + } + if err := decode(req, "untrack", &r); err != nil { + return nil, err + } + ref, err := s.configuredIssue("untrack", r.ExternalID) + if err != nil { + return nil, err + } + status, err := s.gh.rest(ctx, http.MethodDelete, issuePath(ref, "/labels/"+escapePath(s.cfg.TrackedLabel)), nil, nil, http.StatusOK) + if err != nil { + var ae *apiError + // GitHub answers 404 "Label does not exist" for a label the issue + // does not carry. Any other 404 (no such issue, no access) is an + // error. + noMark := errors.As(err, &ae) && status == http.StatusNotFound && strings.Contains(strings.ToLower(ae.Message), "label does not exist") + if !noMark { + return nil, fmt.Errorf("unlabelling %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) + } + } + return map[string]any{"untracked": true, "externalId": r.ExternalID}, nil +} + +const getQuery = `query GetIssue($owner:String!,$name:String!,$number:Int!,$labelsFirst:Int!){ + repository(owner:$owner,name:$name){ + issue(number:$number){number title body state url labels(first:$labelsFirst){nodes{name} pageInfo{hasNextPage}}} + } +}` + +type issueDetail struct { + Number int `json:"number"` + Title string `json:"title"` + Body string `json:"body"` + State string `json:"state"` + URL string `json:"url"` + Labels labelConn `json:"labels"` +} + +func (s *session) readIssue(ctx context.Context, ref issueRef) (*issueDetail, error) { + var data struct { + Repository *struct { + Issue *issueDetail `json:"issue"` + } `json:"repository"` + } + err := s.gh.graphql(ctx, "GetIssue", getQuery, map[string]any{"owner": ref.Owner, "name": ref.Name, "number": ref.Number, "labelsFirst": labelsPerIssue}, &data) + var nf *notFoundError + if errors.As(err, &nf) || err == nil && (data.Repository == nil || data.Repository.Issue == nil) { + return nil, fmt.Errorf("%s/%s#%d: no such issue, or the credential cannot read it", ref.Owner, ref.Name, ref.Number) + } + if err != nil { + return nil, fmt.Errorf("reading %s/%s#%d: %w", ref.Owner, ref.Name, ref.Number, err) + } + return data.Repository.Issue, nil +} + +// get returns one item. Its externalId is the one asked about, as given; +// url is GitHub's canonical URL now (it differs after a transfer or a rename). +func (s *session) get(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + ExternalID string `json:"externalId"` + } + if err := decode(req, "get", &r); err != nil { + return nil, err + } + ref, err := s.configuredIssue("get", r.ExternalID) + if err != nil { + return nil, err + } + is, err := s.readIssue(ctx, ref) + if err != nil { + return nil, err + } + labels, err := (&lister{cfg: s.cfg, gh: s.gh}).labels(ctx, repo{Owner: ref.Owner, Name: ref.Name, Key: ref.Key}, issueNode{Number: is.Number, Labels: is.Labels}) + if err != nil { + return nil, err + } + tracked := false + for _, l := range labels { + tracked = tracked || strings.EqualFold(l, s.cfg.TrackedLabel) + } + // Labels themselves are not returned: tracker labels never reach Hadron + // (cor:agt:120, D7). + return map[string]any{"item": map[string]any{ + "externalId": r.ExternalID, + "title": boundTitle(is.Title), + "body": is.Body, + "state": strings.ToLower(is.State), + "url": is.URL, + "tracked": tracked, + }}, nil +} + +// normalize turns a short reference into the issue's canonical external id, +// as GitHub prints it. +func (s *session) normalize(ctx context.Context, req json.RawMessage) (any, error) { + var r struct { + Ref string `json:"ref"` + } + if err := decode(req, "normalize", &r); err != nil { + return nil, err + } + ref, err := s.cfg.parseShortRef(r.Ref) + if err != nil { + return nil, usageErr("normalize: %q: %v", s.gh.clip(r.Ref, 120), err) + } + if !s.cfg.hasRepo(ref.Owner, ref.Name) { + return nil, usageErr("normalize: %s/%s is not a repository in the adapter's configuration", ref.Owner, ref.Name) + } + is, err := s.readIssue(ctx, ref) + if err != nil { + return nil, err + } + l := &lister{cfg: s.cfg} + id, err := l.externalID(repo{Owner: ref.Owner, Name: ref.Name, Key: ref.Key}, issueNode{Number: is.Number, URL: is.URL}) + if err != nil { + return nil, err + } + return map[string]any{"externalId": id}, nil +} + +type checkResult struct { + Name string `json:"name"` + OK bool `json:"ok"` + Detail string `json:"detail,omitempty"` +} + +// check says whether the configuration is valid, the credential present and +// accepted, and each repository readable. It answers (exit 0) whatever it +// finds; ok is true only when every check passed. +func check(ctx context.Context, getenv func(string) string) any { + results := []checkResult{} + answer := func() any { + ok := true + for _, r := range results { + ok = ok && r.OK + } + return map[string]any{"ok": ok, "checks": results} + } + cfg, err := LoadConfig(getenv) + if err != nil { + results = append(results, checkResult{Name: "configuration", OK: false, Detail: oneLine(err.Error(), 300)}) + return answer() + } + token, err := cfg.Token(getenv) + if err != nil { + results = append(results, checkResult{Name: "credential", OK: false, Detail: oneLine(err.Error(), 300)}) + return answer() + } + gh := newGitHub(cfg, token) + if _, err := gh.rest(ctx, http.MethodGet, "/rate_limit", nil, nil, http.StatusOK); err != nil { + results = append(results, checkResult{Name: "credential", OK: false, Detail: gh.clip(err.Error(), 300)}) + return answer() + } + results = append(results, checkResult{Name: "credential", OK: true}) + for _, r := range cfg.repos() { + name := "repository " + r.Owner + "/" + r.Name + if _, err := gh.rest(ctx, http.MethodGet, "/repos/"+escapePath(r.Owner)+"/"+escapePath(r.Name), nil, nil, http.StatusOK); err != nil { + results = append(results, checkResult{Name: name, OK: false, Detail: gh.clip(err.Error(), 300)}) + continue + } + results = append(results, checkResult{Name: name, OK: true}) + lname := "label " + cfg.TrackedLabel + " in " + r.Owner + "/" + r.Name + if _, err := gh.rest(ctx, http.MethodGet, "/repos/"+escapePath(r.Owner)+"/"+escapePath(r.Name)+"/labels/"+escapePath(cfg.TrackedLabel), nil, nil, http.StatusOK); err != nil { + results = append(results, checkResult{Name: lname, OK: false, Detail: "create it first (gh label create " + cfg.TrackedLabel + " -R " + r.Owner + "/" + r.Name + "): " + gh.clip(err.Error(), 200)}) + continue + } + results = append(results, checkResult{Name: lname, OK: true}) + } + return answer() +} diff --git a/internal/adapter/config.go b/internal/adapter/config.go new file mode 100644 index 0000000..1daaf27 --- /dev/null +++ b/internal/adapter/config.go @@ -0,0 +1,345 @@ +package adapter + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "io/fs" + "net/url" + "os" + "path/filepath" + "regexp" + "strings" + "unicode" +) + +// ConfigEnv names the configuration file. The adapter takes no flags (the +// runner passes exactly one argument, the call), so this and the default +// path are the only ways to point it at a team's configuration. +const ConfigEnv = "TASK_ADAPTER_GITHUB_CONFIG" + +// Limits on the configuration. +const ( + // MaxRepositories keeps the cursor inside the runner's 4096-byte bound + // with GitHub positions up to about 140 bytes each (real ones are about + // 60). A longer position refuses the call instead (list.go). + MaxRepositories = 20 + MaxLabelLen = 100 + MaxExcludeLabels = 50 + MaxTeams = 50 + MaxForPerTeam = 20 + DefaultTracked = "hadron-tracked" + DefaultAPIURL = "https://api.github.com" + DefaultWebHost = "github.com" + maxConfigFileSize = 256 << 10 +) + +// Config is a team's adapter configuration: today's label model +// (cor:agt:120, D7: tracker labels never reach Hadron, they live here), the +// repositories, and how the adapter marks an item tracked. It holds no +// credential: the token is read from the environment. +type Config struct { + // Repositories are "owner/name"; their open issues are the intake. + Repositories []string `json:"repositories"` + // ReadyLabel marks an issue ready for intake. + ReadyLabel string `json:"readyLabel,omitempty"` + // Ready is "only" (list only ready issues; the default when ReadyLabel + // is set), "exclude" or "any" (the default when it is not). + Ready string `json:"ready,omitempty"` + // ExcludeLabels: an issue carrying any of them is never listed. + ExcludeLabels []string `json:"excludeLabels,omitempty"` + // Teams maps the runner's `for` (a worker's name or URN) to a team label, + // or to the issues carrying no team label at all. + Teams []Team `json:"teams,omitempty"` + // TrackedLabel is the adapter's mark. Default "hadron-tracked". + TrackedLabel string `json:"trackedLabel,omitempty"` + // Comment also posts a comment naming the task and worker on mark-tracked. + // Off by default: on a public repository it publishes the team's names. + Comment bool `json:"comment,omitempty"` + // TokenEnv names the environment variable holding the team's GitHub + // token. Unset: GITHUB_TOKEN, then GH_TOKEN. + TokenEnv string `json:"tokenEnv,omitempty"` + // APIURL is the REST base (GitHub Enterprise Server: https://HOST/api/v3). + APIURL string `json:"apiUrl,omitempty"` + // GraphQLURL defaults to APIURL + "/graphql" (Enterprise Server: https://HOST/api/graphql). + GraphQLURL string `json:"graphqlUrl,omitempty"` + // WebHost is the host of issue URLs. Default github.com. + WebHost string `json:"webHost,omitempty"` +} + +// Team is one entry of the team map. +type Team struct { + For []string `json:"for"` + Label string `json:"label,omitempty"` + NoTeam bool `json:"noTeam,omitempty"` +} + +// repo is one configured repository. +type repo struct { + Owner, Name string + Key string // lower-cased "owner/name" +} + +var repoSegment = regexp.MustCompile(`^[A-Za-z0-9._-]+$`) + +// validSegment is one segment of "owner/name": GitHub's characters, and never +// "." or "..", which would make a path out of a name. +func validSegment(s string) bool { + return repoSegment.MatchString(s) && s != "." && s != ".." +} + +// ConfigPath is where the configuration is read from. +func ConfigPath(getenv func(string) string) (string, error) { + if p := getenv(ConfigEnv); p != "" { + return p, nil + } + dir, err := os.UserConfigDir() + if err != nil { + return "", fmt.Errorf("no configuration: set %s, or create it under the user configuration directory", ConfigEnv) + } + return filepath.Join(dir, "hadron-task-adapter-github", "config.json"), nil +} + +// LoadConfig reads and validates the configuration. +func LoadConfig(getenv func(string) string) (*Config, error) { + p, err := ConfigPath(getenv) + if err != nil { + return nil, err + } + b, err := readBounded(p, maxConfigFileSize) + if errors.Is(err, fs.ErrNotExist) { + return nil, fmt.Errorf("no configuration at %s (set %s to its path; see config.example.json)", p, ConfigEnv) + } + if err != nil { + return nil, fmt.Errorf("reading the configuration %s: %v", p, err) + } + return ParseConfig(b) +} + +func readBounded(p string, max int64) ([]byte, error) { + f, err := os.Open(p) + if err != nil { + return nil, err + } + defer f.Close() + b, err := io.ReadAll(io.LimitReader(f, max+1)) + if err != nil { + return nil, err + } + if int64(len(b)) > max { + return nil, fmt.Errorf("larger than %d bytes", max) + } + return b, nil +} + +// ParseConfig decodes and validates a configuration. Unknown keys are +// refused: a misspelt label key would otherwise silently widen the intake. +func ParseConfig(b []byte) (*Config, error) { + dec := json.NewDecoder(bytes.NewReader(b)) + dec.DisallowUnknownFields() + var c Config + if err := dec.Decode(&c); err != nil { + return nil, fmt.Errorf("configuration: %v", err) + } + if _, err := dec.Token(); err != io.EOF { + return nil, errors.New("configuration: text after the JSON object") + } + if err := c.validate(); err != nil { + return nil, fmt.Errorf("configuration: %v", err) + } + return &c, nil +} + +func checkLabel(field, l string) error { + if l == "" || len([]rune(l)) > MaxLabelLen { + return fmt.Errorf("%s: a label is 1 to %d characters", field, MaxLabelLen) + } + for _, r := range l { + if unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return fmt.Errorf("%s: a label may not contain control or invisible format characters", field) + } + } + return nil +} + +func (c *Config) validate() error { + if len(c.Repositories) == 0 || len(c.Repositories) > MaxRepositories { + return fmt.Errorf("repositories: list 1 to %d repositories", MaxRepositories) + } + seen := map[string]bool{} + for i, r := range c.Repositories { + parts := strings.Split(r, "/") + if len(parts) != 2 || !validSegment(parts[0]) || !validSegment(parts[1]) { + return fmt.Errorf("repositories[%d]: %q is not \"owner/name\"", i, r) + } + k := strings.ToLower(r) + if seen[k] { + return fmt.Errorf("repositories[%d]: %q is listed twice", i, r) + } + seen[k] = true + } + if c.ReadyLabel != "" { + if err := checkLabel("readyLabel", c.ReadyLabel); err != nil { + return err + } + } + switch c.Ready { + case "": + c.Ready = "any" + if c.ReadyLabel != "" { + c.Ready = "only" + } + case "only", "exclude": + if c.ReadyLabel == "" { + return fmt.Errorf("ready: %q needs a readyLabel", c.Ready) + } + case "any": + default: + return fmt.Errorf("ready: %q is not one of only, exclude, any", c.Ready) + } + if len(c.ExcludeLabels) > MaxExcludeLabels { + return fmt.Errorf("excludeLabels: at most %d", MaxExcludeLabels) + } + for i, l := range c.ExcludeLabels { + if err := checkLabel(fmt.Sprintf("excludeLabels[%d]", i), l); err != nil { + return err + } + } + if len(c.Teams) > MaxTeams { + return fmt.Errorf("teams: at most %d", MaxTeams) + } + who := map[string]bool{} + for i, t := range c.Teams { + at := fmt.Sprintf("teams[%d]", i) + if len(t.For) == 0 || len(t.For) > MaxForPerTeam { + return fmt.Errorf("%s.for: name 1 to %d workers (names or URNs)", at, MaxForPerTeam) + } + for j, f := range t.For { + if strings.TrimSpace(f) == "" || len(f) > 512 { + return fmt.Errorf("%s.for[%d]: a worker name or URN of 1 to 512 bytes", at, j) + } + k := strings.ToLower(f) + if who[k] { + return fmt.Errorf("%s.for[%d]: %q is mapped to another team already", at, j, f) + } + who[k] = true + } + switch { + case t.NoTeam && t.Label != "": + return fmt.Errorf("%s: a team has a label or noTeam, not both", at) + case !t.NoTeam: + if err := checkLabel(at+".label", t.Label); err != nil { + return err + } + } + } + if c.TrackedLabel == "" { + c.TrackedLabel = DefaultTracked + } + if err := checkLabel("trackedLabel", c.TrackedLabel); err != nil { + return err + } + if strings.EqualFold(c.TrackedLabel, c.ReadyLabel) { + return errors.New("trackedLabel: must differ from readyLabel") + } + if c.TokenEnv != "" { + if !regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`).MatchString(c.TokenEnv) { + return fmt.Errorf("tokenEnv: %q is not an environment variable name", c.TokenEnv) + } + // The hadron CLI strips HADRON_* credentials from the adapter's + // environment (cor:agt:120, D2): such a variable never arrives. + if strings.HasPrefix(strings.ToUpper(c.TokenEnv), "HADRON_") { + return errors.New("tokenEnv: a HADRON_ variable is never passed to the adapter; the GitHub token is the team's own") + } + } + if c.APIURL == "" { + c.APIURL = DefaultAPIURL + } + c.APIURL = strings.TrimRight(c.APIURL, "/") + if err := checkEndpoint("apiUrl", c.APIURL); err != nil { + return err + } + if c.GraphQLURL == "" { + c.GraphQLURL = c.APIURL + "/graphql" + } + if err := checkEndpoint("graphqlUrl", c.GraphQLURL); err != nil { + return err + } + if c.WebHost == "" { + c.WebHost = DefaultWebHost + } + if strings.ContainsAny(c.WebHost, "/@: \t") { + return fmt.Errorf("webHost: %q is a host name, not a URL", c.WebHost) + } + return nil +} + +// checkEndpoint: the token is sent there, so it is https, or plain http only +// to the loopback interface (a local fake or proxy). +func checkEndpoint(field, raw string) error { + u, err := url.Parse(raw) + if err != nil || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" { + return fmt.Errorf("%s: %q is not a plain https URL", field, raw) + } + switch u.Scheme { + case "https": + return nil + case "http": + h := u.Hostname() + if h == "localhost" || h == "127.0.0.1" || h == "::1" { + return nil + } + } + return fmt.Errorf("%s: %q must be https (http only to the loopback interface)", field, raw) +} + +func (c *Config) repos() []repo { + out := make([]repo, 0, len(c.Repositories)) + for _, r := range c.Repositories { + o, n, _ := strings.Cut(r, "/") + out = append(out, repo{Owner: o, Name: n, Key: strings.ToLower(r)}) + } + return out +} + +func (c *Config) hasRepo(owner, name string) bool { + k := strings.ToLower(owner + "/" + name) + for _, r := range c.repos() { + if r.Key == k { + return true + } + } + return false +} + +// team resolves the runner's `for`. ok is false when `for` is given and no +// team maps it. +func (c *Config) team(forWorker string) (t *Team, ok bool) { + if forWorker == "" { + return nil, true + } + for i := range c.Teams { + for _, f := range c.Teams[i].For { + if strings.EqualFold(f, forWorker) { + return &c.Teams[i], true + } + } + } + return nil, false +} + +// Token returns the team's GitHub token from the environment. +func (c *Config) Token(getenv func(string) string) (string, error) { + names := []string{"GITHUB_TOKEN", "GH_TOKEN"} + if c.TokenEnv != "" { + names = []string{c.TokenEnv} + } + for _, n := range names { + if v := strings.TrimSpace(getenv(n)); v != "" { + return v, nil + } + } + return "", fmt.Errorf("no GitHub credential: set %s to the team's own GitHub token (never a Hadron one)", strings.Join(names, " or ")) +} diff --git a/internal/adapter/config_test.go b/internal/adapter/config_test.go new file mode 100644 index 0000000..781632f --- /dev/null +++ b/internal/adapter/config_test.go @@ -0,0 +1,199 @@ +package adapter + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +func TestConfigRefusals(t *testing.T) { + cases := map[string]string{ + "no repositories": `{"repositories":[]}`, + "not owner/name": `{"repositories":["acme"]}`, + "path in name": `{"repositories":["acme/app/x"]}`, + "dot name": `{"repositories":["acme/.."]}`, + "dot owner": `{"repositories":["../app"]}`, + "duplicate repo": `{"repositories":["acme/app","ACME/App"]}`, + "unknown key": `{"repositories":["acme/app"],"readyLable":"x"}`, + "two values": `{"repositories":["acme/app"]}{}`, + "trailing bracket": `{"repositories":["acme/app"]}]`, + "trailing brace": `{"repositories":["acme/app"]}}`, + "twenty-one repositories": `{"repositories":[` + manyRepos(21) + `]}`, + "ready only without label": `{"repositories":["acme/app"],"ready":"only"}`, + "ready unknown": `{"repositories":["acme/app"],"readyLabel":"r","ready":"some"}`, + "control in label": "{\"repositories\":[\"acme/app\"],\"readyLabel\":\"a\\u0007b\"}", + "format char in label": "{\"repositories\":[\"acme/app\"],\"excludeLabels\":[\"a\\u200bb\"]}", + "team without for": `{"repositories":["acme/app"],"teams":[{"for":[],"label":"t"}]}`, + "team with label and none": `{"repositories":["acme/app"],"teams":[{"for":["a"],"label":"t","noTeam":true}]}`, + "team without label": `{"repositories":["acme/app"],"teams":[{"for":["a"]}]}`, + "worker in two teams": `{"repositories":["acme/app"],"teams":[{"for":["Ada"],"label":"t"},{"for":["ada"],"label":"u"}]}`, + "tracked equals ready": `{"repositories":["acme/app"],"readyLabel":"x","trackedLabel":"X"}`, + "hadron token env": `{"repositories":["acme/app"],"tokenEnv":"HADRON_GITHUB_TOKEN"}`, + "bad token env": `{"repositories":["acme/app"],"tokenEnv":"A-B"}`, + "plain http to remote": `{"repositories":["acme/app"],"apiUrl":"http://api.example.com"}`, + "userinfo in api url": `{"repositories":["acme/app"],"apiUrl":"https://u:p@api.example.com"}`, + "web host with scheme": `{"repositories":["acme/app"],"webHost":"https://github.com"}`, + "graphql url to plain http": `{"repositories":["acme/app"],"graphqlUrl":"http://example.com/graphql"}`, + } + for name, raw := range cases { + t.Run(name, func(t *testing.T) { + if _, err := ParseConfig([]byte(raw)); err == nil { + t.Fatalf("accepted %s", raw) + } + }) + } +} + +func manyRepos(n int) string { + parts := []string{} + for i := 0; i < n; i++ { + parts = append(parts, `"o/r`+strings.Repeat("x", i)+`"`) + } + return strings.Join(parts, ",") +} + +func TestConfigDefaults(t *testing.T) { + c, err := ParseConfig([]byte(`{"repositories":["acme/app"],"readyLabel":"cleared"}`)) + if err != nil { + t.Fatal(err) + } + if c.Ready != "only" || c.TrackedLabel != DefaultTracked || c.APIURL != DefaultAPIURL || c.GraphQLURL != DefaultAPIURL+"/graphql" || c.WebHost != DefaultWebHost { + t.Fatalf("defaults: %+v", c) + } + c, err = ParseConfig([]byte(`{"repositories":["acme/app"],"apiUrl":"https://ghe.example.com/api/v3/","graphqlUrl":"https://ghe.example.com/api/graphql","webHost":"ghe.example.com"}`)) + if err != nil { + t.Fatal(err) + } + if c.Ready != "any" || c.APIURL != "https://ghe.example.com/api/v3" { + t.Fatalf("enterprise: %+v", c) + } +} + +func TestTokenLookup(t *testing.T) { + c, _ := ParseConfig([]byte(`{"repositories":["acme/app"]}`)) + env := map[string]string{"GH_TOKEN": "b"} + if tok, err := c.Token(func(k string) string { return env[k] }); err != nil || tok != "b" { + t.Fatalf("GH_TOKEN: %q %v", tok, err) + } + env["GITHUB_TOKEN"] = "a" + if tok, _ := c.Token(func(k string) string { return env[k] }); tok != "a" { + t.Fatalf("GITHUB_TOKEN first: %q", tok) + } + c.TokenEnv = "TEAM_GH" + if _, err := c.Token(func(k string) string { return env[k] }); err == nil { + t.Fatal("tokenEnv set but empty: fell back to another variable") + } +} + +func TestConfigFileIsBounded(t *testing.T) { + p := filepath.Join(t.TempDir(), "c.json") + if err := os.WriteFile(p, []byte(`{"repositories":["acme/app"],"readyLabel":"`+strings.Repeat("a", maxConfigFileSize)+`"}`), 0o600); err != nil { + t.Fatal(err) + } + if _, err := LoadConfig(func(k string) string { + if k == ConfigEnv { + return p + } + return "" + }); err == nil || !strings.Contains(err.Error(), "larger than") { + t.Fatalf("an oversized configuration: %v", err) + } +} + +func TestParseIssueURL(t *testing.T) { + good := map[string]issueRef{ + "https://github.com/Acme/App/issues/12": {Owner: "Acme", Name: "App", Key: "acme/app", Number: 12}, + } + for raw, want := range good { + got, err := parseIssueURL(raw, "github.com") + if err != nil || got != want { + t.Fatalf("%s: %+v %v", raw, got, err) + } + } + for _, raw := range []string{ + "http://github.com/acme/app/issues/1", + "https://evil.example/acme/app/issues/1", + "https://u@github.com/acme/app/issues/1", + "https://github.com:443/acme/app/issues/1", + "https://github.com/acme/app/pull/1", + "https://github.com/acme/app/issues/1/", + "https://github.com/acme/app/issues/01", + "https://github.com/acme/app/issues/0", + "https://github.com/acme/app/issues/1?x=1", + "https://github.com/acme/app/issues/1#c", + "https://github.com/acme/app/issues/1/comments", + "https://github.com/acme/../issues/1", + "https://github.com/acme/app%2fx/issues/1", + } { + if _, err := parseIssueURL(raw, "github.com"); err == nil { + t.Errorf("accepted %s", raw) + } + } +} + +func TestCheckExternalID(t *testing.T) { + for _, bad := range []string{"", "https://github.com/a/b/issues/1 ", "https://x/\u200b", "https://u:p@github.com/a", strings.Repeat("a", 513)} { + if checkExternalID(bad) == nil { + t.Errorf("accepted %q", bad) + } + } + if err := checkExternalID(strings.Repeat("é", 512)); err != nil { + t.Errorf("512 code points refused: %v", err) + } +} + +func TestOneLineAndBoundTitle(t *testing.T) { + if got := oneLine("a\n\tb\u202ec\x1b[31m", 50); got != "a b c [31m" { + t.Fatalf("oneLine: %q", got) + } + long := strings.Repeat("é", 700) // 1400 bytes + got := boundTitle(long) + if len(got) > 1024 || !strings.HasSuffix(got, "…") { + t.Fatalf("boundTitle: %d bytes", len(got)) + } +} + +// The example the README points at is a valid configuration. +func TestExampleConfigParses(t *testing.T) { + b, err := os.ReadFile(filepath.Join("..", "..", "config.example.json")) + if err != nil { + t.Fatal(err) + } + if _, err := ParseConfig(b); err != nil { + t.Fatalf("config.example.json: %v", err) + } +} + +// A fragment of the credential is redacted wherever a cut can leave one: +// text that arrives already truncated (a proxy echoing a cut token), and a +// cut of ours that lands inside it (Ada's ruling on the LOCAL delta F3). +func TestClipRedactsAnyFragmentOfTheCredential(t *testing.T) { + const tok = "ghp_FAKEunitTOKEN000000000000000000000000" + g := &githubClient{token: tok} + // Text that arrives already cut: any prefix right before the ellipsis, + // and any prefix of 8 runes or more anywhere. + for k := 1; k < len(tok); k++ { + for _, tail := range []string{"…", " and more"} { + in := "bad URL https://github.com/a/b/issues/1?echo=" + tok[:k] + tail + got := g.clip(in, 200) + if strings.Contains(got, tok[:k]+"…") || (k >= 8 && strings.Contains(got, tok[:k])) { + t.Fatalf("prefix %d (tail %q) survived: %q", k, tail, got) + } + } + } + // A cut of ours, at every length. + for max := 1; max < 120; max++ { + got := g.clip(strings.Repeat("x", 40)+tok+" tail", max) + if strings.Contains(got, tok[:8]) || strings.Contains(got, "g…") { + t.Fatalf("cut at %d leaked: %q", max, got) + } + } + // The whole credential is replaced exactly, leaving none of it behind. + if got := g.clip("a "+tok+" b", 200); got != "a [redacted] b" { + t.Fatalf("whole credential: %q", got) + } + if got := g.clip("plain text, no credential", 200); got != "plain text, no credential" { + t.Fatalf("clean text changed: %q", got) + } +} diff --git a/internal/adapter/github.go b/internal/adapter/github.go new file mode 100644 index 0000000..da1d0e5 --- /dev/null +++ b/internal/adapter/github.go @@ -0,0 +1,196 @@ +package adapter + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "strings" + "time" +) + +const ( + maxResponseBytes = 16 << 20 + requestTimeout = 20 * time.Second + userAgent = "hadron-task-adapter-github" +) + +// githubClient calls GitHub with the team's token. The token is only ever +// put in the Authorization header: no error message, log line or answer +// carries it, and GitHub's own error text is scrubbed of it before it is +// repeated. +type githubClient struct { + http *http.Client + api, gql string + token string +} + +func newGitHub(c *Config, token string) *githubClient { + return &githubClient{http: &http.Client{Timeout: requestTimeout}, api: c.APIURL, gql: c.GraphQLURL, token: token} +} + +// apiError is a GitHub answer the adapter will not use. +type apiError struct { + Status int + Message string +} + +func (e *apiError) Error() string { + if e.Status == 0 { + return "GitHub: " + e.Message + } + return fmt.Sprintf("GitHub answered %d: %s", e.Status, e.Message) +} + +func (g *githubClient) scrub(s string) string { + return g.clip(s, 200) +} + +// clip quotes untrusted text on one line, cut to max runes, with the +// credential scrubbed FIRST: a cut that lands inside the credential would +// otherwise leave a prefix that no later scrub can recognise. +func (g *githubClient) clip(s string, max int) string { + return oneLine(redact(s, g.token), max) +} + +// minFragment is the shortest prefix of the credential redacted wherever +// it appears; a shorter one is redacted only where a cut left it. +const minFragment = 8 + +// redact removes the credential from s: whole, as any prefix of at least +// minFragment runes, and as any prefix at all right before the ellipsis a +// cut leaves. Text can arrive already cut (a proxy echoing a truncated +// token), and a cut can land inside the credential. +func redact(s, token string) string { + if token == "" { + return s + } + s = strings.ReplaceAll(s, token, "[redacted]") + for k := len(token) - 1; k >= 1; k-- { + p := token[:k] + if k >= minFragment { + s = strings.ReplaceAll(s, p, "[redacted]") + } else { + s = strings.ReplaceAll(s, p+"…", "[redacted]…") + } + } + return s +} + +func (g *githubClient) do(ctx context.Context, method, endpoint string, body any) (int, []byte, error) { + var rd io.Reader + if body != nil { + b, err := json.Marshal(body) + if err != nil { + return 0, nil, err + } + rd = bytes.NewReader(b) + } + req, err := http.NewRequestWithContext(ctx, method, endpoint, rd) + if err != nil { + return 0, nil, err + } + req.Header.Set("Authorization", "Bearer "+g.token) + req.Header.Set("Accept", "application/vnd.github+json") + req.Header.Set("X-GitHub-Api-Version", "2022-11-28") + req.Header.Set("User-Agent", userAgent) + if body != nil { + req.Header.Set("Content-Type", "application/json") + } + resp, err := g.http.Do(req) + if err != nil { + // A transport error can quote the URL, never the header; scrub anyway. + return 0, nil, &apiError{Message: g.scrub(err.Error())} + } + defer resp.Body.Close() + b, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes+1)) + if err != nil { + return 0, nil, &apiError{Status: resp.StatusCode, Message: "the answer could not be read"} + } + if len(b) > maxResponseBytes { + return 0, nil, &apiError{Status: resp.StatusCode, Message: "the answer is larger than the adapter reads"} + } + if resp.StatusCode == http.StatusForbidden || resp.StatusCode == http.StatusTooManyRequests { + if resp.Header.Get("X-RateLimit-Remaining") == "0" || resp.Header.Get("Retry-After") != "" { + return resp.StatusCode, b, &apiError{Status: resp.StatusCode, Message: "rate limited; try again later"} + } + } + return resp.StatusCode, b, nil +} + +func (g *githubClient) errorFrom(status int, b []byte) error { + var m struct { + Message string `json:"message"` + } + _ = json.Unmarshal(b, &m) + msg := m.Message + if msg == "" { + msg = http.StatusText(status) + } + return &apiError{Status: status, Message: g.scrub(msg)} +} + +// rest makes one REST call. ok lists the statuses that are an answer; any +// other is an error. out may be nil. +func (g *githubClient) rest(ctx context.Context, method, path string, body any, out any, ok ...int) (int, error) { + status, b, err := g.do(ctx, method, g.api+path, body) + if err != nil { + return status, err + } + for _, s := range ok { + if status == s { + if out != nil && len(b) > 0 { + if err := json.Unmarshal(b, out); err != nil { + return status, &apiError{Status: status, Message: "an answer the adapter does not understand"} + } + } + return status, nil + } + } + return status, g.errorFrom(status, b) +} + +// graphql makes one GraphQL query. Any error in the answer fails the call: +// a partial answer is never read as a whole one. +func (g *githubClient) graphql(ctx context.Context, op, query string, vars map[string]any, out any) error { + status, b, err := g.do(ctx, http.MethodPost, g.gql, map[string]any{"query": query, "operationName": op, "variables": vars}) + if err != nil { + return err + } + if status != http.StatusOK { + return g.errorFrom(status, b) + } + var env struct { + Data json.RawMessage `json:"data"` + Errors []struct { + Type string `json:"type"` + Message string `json:"message"` + } `json:"errors"` + } + if err := json.Unmarshal(b, &env); err != nil { + return &apiError{Status: status, Message: "an answer the adapter does not understand"} + } + if len(env.Errors) > 0 { + e := env.Errors[0] + if e.Type == "NOT_FOUND" { + return ¬FoundError{msg: g.scrub(e.Message)} + } + return &apiError{Status: status, Message: g.scrub(e.Message)} + } + if len(env.Data) == 0 || string(env.Data) == "null" { + return &apiError{Status: status, Message: "an answer with no data"} + } + if err := json.Unmarshal(env.Data, out); err != nil { + return &apiError{Status: status, Message: "an answer the adapter does not understand"} + } + return nil +} + +type notFoundError struct{ msg string } + +func (e *notFoundError) Error() string { return "GitHub: " + e.msg } + +func escapePath(s string) string { return url.PathEscape(s) } diff --git a/internal/adapter/list.go b/internal/adapter/list.go new file mode 100644 index 0000000..8b86da6 --- /dev/null +++ b/internal/adapter/list.go @@ -0,0 +1,345 @@ +package adapter + +import ( + "context" + "crypto/sha256" + "encoding/base64" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "net/http" + "strings" + "time" +) + +const ( + issuesPerRequest = 100 + labelsPerIssue = 100 + maxLabelPages = 10 // REST fallback: 1000 labels on one issue + // A call reads at most this many GitHub pages beyond the first of each + // repository, then answers with what it has and a cursor. Filtering + // happens here, so a run of ineligible issues costs reads, not items. + extraFetchesPerCall = 20 + cursorPrefix = "v1." + // MaxCursorLen is the hadron CLI runner's bound on nextCursor. + MaxCursorLen = 4096 +) + +const listQuery = `query ListOpenIssues($owner:String!,$name:String!,$after:String,$first:Int!,$labelsFirst:Int!){ + repository(owner:$owner,name:$name){ + issues(states:OPEN,first:$first,after:$after,orderBy:{field:CREATED_AT,direction:ASC}){ + pageInfo{hasNextPage} + edges{cursor node{number title url createdAt labels(first:$labelsFirst){nodes{name} pageInfo{hasNextPage}}}} + } + } +}` + +type labelConn struct { + Nodes []struct{ Name string } `json:"nodes"` + PageInfo struct { + HasNextPage bool `json:"hasNextPage"` + } `json:"pageInfo"` +} + +type issueNode struct { + Number int `json:"number"` + Title string `json:"title"` + URL string `json:"url"` + CreatedAt time.Time `json:"createdAt"` + Labels labelConn `json:"labels"` +} + +type issueEdge struct { + Cursor string `json:"cursor"` + Node issueNode `json:"node"` +} + +// repoWalk is the position in one repository's open issues, oldest first. +type repoWalk struct { + repo + after string // GitHub's cursor after the last issue consumed; "" = the start + done bool + fetched bool + more bool + buf []issueEdge +} + +// cursorState is what the adapter's opaque cursor carries: a fingerprint of +// the query (the configuration's filters, its repositories and `for`), and +// per configured repository GitHub's own cursor, or null once it is done. +type cursorState struct { + Query string `json:"q"` + Pos []*string `json:"p"` +} + +func (c *Config) fingerprint(forWorker string) string { + b, _ := json.Marshal([]any{c.Repositories, c.ReadyLabel, c.Ready, c.ExcludeLabels, c.Teams, c.TrackedLabel, strings.ToLower(forWorker)}) + sum := sha256.Sum256(b) + return hex.EncodeToString(sum[:8]) +} + +func encodeCursor(s cursorState) string { + b, _ := json.Marshal(s) + return cursorPrefix + base64.RawURLEncoding.EncodeToString(b) +} + +func decodeCursor(raw string, want string, n int) (cursorState, error) { + bad := errors.New("the cursor is not one this adapter issued") + if !strings.HasPrefix(raw, cursorPrefix) { + return cursorState{}, bad + } + b, err := base64.RawURLEncoding.DecodeString(strings.TrimPrefix(raw, cursorPrefix)) + if err != nil { + return cursorState{}, bad + } + var s cursorState + if err := json.Unmarshal(b, &s); err != nil || len(s.Pos) != n { + return cursorState{}, bad + } + if s.Query != want { + return cursorState{}, errors.New("the cursor was issued for another query or before the configuration changed; start the list again") + } + return s, nil +} + +// lister lists untracked issues. +type lister struct { + cfg *Config + gh *githubClient +} + +func (l *lister) fetch(ctx context.Context, w *repoWalk) error { + vars := map[string]any{"owner": w.Owner, "name": w.Name, "first": issuesPerRequest, "labelsFirst": labelsPerIssue} + if w.after != "" { + vars["after"] = w.after + } + var data struct { + Repository *struct { + Issues *struct { + PageInfo struct { + HasNextPage bool `json:"hasNextPage"` + } `json:"pageInfo"` + Edges []issueEdge `json:"edges"` + } `json:"issues"` + } `json:"repository"` + } + if err := l.gh.graphql(ctx, "ListOpenIssues", listQuery, vars, &data); err != nil { + return fmt.Errorf("reading %s/%s: %w", w.Owner, w.Name, err) + } + if data.Repository == nil || data.Repository.Issues == nil { + return fmt.Errorf("reading %s/%s: GitHub returned no issue list", w.Owner, w.Name) + } + iss := data.Repository.Issues + for _, e := range iss.Edges { + if e.Cursor == "" || e.Node.URL == "" || e.Node.Number <= 0 || e.Node.CreatedAt.IsZero() { + return fmt.Errorf("reading %s/%s: GitHub returned an incomplete issue", w.Owner, w.Name) + } + } + w.buf, w.more, w.fetched = iss.Edges, iss.PageInfo.HasNextPage, true + // An empty page that still promises more would never make progress. + if len(w.buf) == 0 && w.more { + return fmt.Errorf("reading %s/%s: GitHub returned an empty page that promises more", w.Owner, w.Name) + } + return nil +} + +// labels returns all of an issue's labels, reading past the first page. +func (l *lister) labels(ctx context.Context, r repo, n issueNode) ([]string, error) { + out := make([]string, 0, len(n.Labels.Nodes)) + if !n.Labels.PageInfo.HasNextPage { + for _, x := range n.Labels.Nodes { + out = append(out, x.Name) + } + return out, nil + } + for page := 1; ; page++ { + if page > maxLabelPages { + return nil, fmt.Errorf("%s/%s#%d carries more than %d labels", r.Owner, r.Name, n.Number, maxLabelPages*100) + } + var got []struct{ Name string } + path := fmt.Sprintf("/repos/%s/%s/issues/%d/labels?per_page=100&page=%d", escapePath(r.Owner), escapePath(r.Name), n.Number, page) + if _, err := l.gh.rest(ctx, http.MethodGet, path, nil, &got, http.StatusOK); err != nil { + return nil, fmt.Errorf("reading the labels of %s/%s#%d: %w", r.Owner, r.Name, n.Number, err) + } + for _, x := range got { + out = append(out, x.Name) + } + if len(got) < 100 { + return out, nil + } + } +} + +// eligible applies the label model to one issue (labels compared without +// regard to case). +func (l *lister) eligible(labels []string, t *Team) bool { + has := map[string]bool{} + for _, x := range labels { + has[strings.ToLower(x)] = true + } + if has[strings.ToLower(l.cfg.TrackedLabel)] { + return false + } + for _, x := range l.cfg.ExcludeLabels { + if has[strings.ToLower(x)] { + return false + } + } + if t != nil { + if t.NoTeam { + for _, other := range l.cfg.Teams { + if !other.NoTeam && has[strings.ToLower(other.Label)] { + return false + } + } + } else if !has[strings.ToLower(t.Label)] { + return false + } + } + ready := l.cfg.ReadyLabel != "" && has[strings.ToLower(l.cfg.ReadyLabel)] + switch l.cfg.Ready { + case "only": + return ready + case "exclude": + return !ready + } + return true +} + +// before is the list's order: oldest first, then repository, then number. +func before(a, b *repoWalk) bool { + x, y := a.buf[0].Node, b.buf[0].Node + if !x.CreatedAt.Equal(y.CreatedAt) { + return x.CreatedAt.Before(y.CreatedAt) + } + if a.Key != b.Key { + return a.Key < b.Key + } + return x.Number < y.Number +} + +type listedItem struct { + ExternalID string `json:"externalId"` + Title string `json:"title"` +} + +// list answers one list-untracked page: up to limit eligible issues in the +// list's order, and the cursor to resume after the last issue consumed (nil +// when every repository is done). +// +// The set of open issues does not shrink when an issue is marked: the mark is +// a label, and filtering happens here, after GitHub's paging. So a cursor +// taken before others marked issues still resumes at the right place. +func (l *lister) list(ctx context.Context, cursor, forWorker string, limit int) ([]listedItem, *string, error) { + team, ok := l.cfg.team(forWorker) + if !ok { + return nil, nil, usageErr("no team in the adapter's configuration is mapped to the worker %q", l.gh.clip(forWorker, 80)) + } + repos := l.cfg.repos() + fp := l.cfg.fingerprint(forWorker) + walks := make([]*repoWalk, len(repos)) + for i, r := range repos { + walks[i] = &repoWalk{repo: r} + } + if cursor != "" { + s, err := decodeCursor(cursor, fp, len(repos)) + if err != nil { + return nil, nil, usageErr("%v", err) + } + for i, p := range s.Pos { + if p == nil { + walks[i].done = true + } else { + walks[i].after = *p + } + } + } + items := []listedItem{} + budget := len(walks) + extraFetchesPerCall + stopped := false + for len(items) < limit { + var head *repoWalk + for _, w := range walks { + if w.done { + continue + } + if len(w.buf) == 0 { + if w.fetched && !w.more { + w.done = true + continue + } + if budget == 0 { + stopped = true + break + } + budget-- + if err := l.fetch(ctx, w); err != nil { + return nil, nil, err + } + if len(w.buf) == 0 { + w.done = true + continue + } + } + if head == nil || before(w, head) { + head = w + } + } + // Out of reads before every repository showed its next issue: the + // order cannot be decided, so answer with what is decided. + if stopped || head == nil { + break + } + e := head.buf[0] + head.buf = head.buf[1:] + head.after = e.Cursor + if len(head.buf) == 0 && !head.more { + head.done = true + } + labels, err := l.labels(ctx, head.repo, e.Node) + if err != nil { + return nil, nil, err + } + if !l.eligible(labels, team) { + continue + } + id, err := l.externalID(head.repo, e.Node) + if err != nil { + return nil, nil, err + } + items = append(items, listedItem{ExternalID: id, Title: boundTitle(e.Node.Title)}) + } + allDone := true + pos := make([]*string, len(walks)) + for i, w := range walks { + if !w.done { + allDone = false + a := w.after + pos[i] = &a + } + } + if allDone { + return items, nil, nil + } + next := encodeCursor(cursorState{Query: fp, Pos: pos}) + // The runner refuses a cursor past its bound; GitHub does not promise + // how long its positions are. Never answer with one that cannot be used. + if len(next) > MaxCursorLen { + return nil, nil, fmt.Errorf("the cursor would be %d bytes, more than the %d the hadron CLI accepts (GitHub's positions are unusually long); configure fewer repositories", len(next), MaxCursorLen) + } + return items, &next, nil +} + +// externalID is the issue's canonical URL as GitHub prints it, checked to be +// an issue URL of the repository it was read from and a valid external id. +func (l *lister) externalID(r repo, n issueNode) (string, error) { + ref, err := parseIssueURL(n.URL, l.cfg.WebHost) + if err != nil || ref.Key != r.Key || ref.Number != n.Number { + return "", fmt.Errorf("GitHub returned %q for %s/%s#%d, which is not that issue's URL", l.gh.clip(n.URL, 120), r.Owner, r.Name, n.Number) + } + if err := checkExternalID(n.URL); err != nil { + return "", fmt.Errorf("GitHub returned an issue URL that is not a valid external id: %v", err) + } + return n.URL, nil +} diff --git a/internal/adapter/refs.go b/internal/adapter/refs.go new file mode 100644 index 0000000..8bad79c --- /dev/null +++ b/internal/adapter/refs.go @@ -0,0 +1,130 @@ +package adapter + +import ( + "errors" + "fmt" + "net/url" + "strconv" + "strings" + "unicode" + "unicode/utf8" +) + +// issueRef is an issue named by an external id or a short reference. +type issueRef struct { + Owner, Name string + Key string // lower-cased owner/name + Number int +} + +// parseIssueURL reads https://///issues/, exactly: +// no userinfo, query, fragment, port or trailing path. It is how an external +// id the CLI hands back is read, so it accepts only the shape list-untracked +// produces. +func parseIssueURL(raw, host string) (issueRef, error) { + u, err := url.Parse(raw) + if err != nil { + return issueRef{}, errors.New("not a URL") + } + if u.Scheme != "https" || !strings.EqualFold(u.Host, host) || u.User != nil || u.RawQuery != "" || u.Fragment != "" || u.Opaque != "" { + return issueRef{}, fmt.Errorf("not an issue URL on %s", host) + } + parts := strings.Split(strings.TrimPrefix(u.EscapedPath(), "/"), "/") + if len(parts) != 4 || parts[2] != "issues" || !validSegment(parts[0]) || !validSegment(parts[1]) { + return issueRef{}, fmt.Errorf("not an issue URL (https://%s///issues/)", host) + } + n, err := strconv.Atoi(parts[3]) + if err != nil || n <= 0 || strconv.Itoa(n) != parts[3] { + return issueRef{}, errors.New("the issue number is not a positive number") + } + return issueRef{Owner: parts[0], Name: parts[1], Key: strings.ToLower(parts[0] + "/" + parts[1]), Number: n}, nil +} + +// parseShortRef reads the forms normalize accepts: an issue URL in any case +// and with a trailing slash, "owner/name#N", and "#N" when exactly one +// repository is configured. +func (c *Config) parseShortRef(ref string) (issueRef, error) { + ref = strings.TrimSpace(ref) + if strings.HasPrefix(strings.ToLower(ref), "https://") { + return parseIssueURL(strings.TrimSuffix(ref, "/"), c.WebHost) + } + repoPart, num, ok := strings.Cut(ref, "#") + if !ok { + return issueRef{}, errors.New(`a reference is an issue URL, "owner/name#N" or "#N"`) + } + n, err := strconv.Atoi(num) + if err != nil || n <= 0 { + return issueRef{}, errors.New("the issue number is not a positive number") + } + if repoPart == "" { + if len(c.Repositories) != 1 { + return issueRef{}, errors.New(`"#N" names an issue only when exactly one repository is configured`) + } + repoPart = c.Repositories[0] + } + o, name, ok := strings.Cut(repoPart, "/") + if !ok || !validSegment(o) || !validSegment(name) { + return issueRef{}, errors.New(`a reference is an issue URL, "owner/name#N" or "#N"`) + } + return issueRef{Owner: o, Name: name, Key: strings.ToLower(o + "/" + name), Number: n}, nil +} + +// checkExternalID applies the external id's checks (cor:agt:120:02): 1 to +// 512 characters, no whitespace, control or invisible format characters, no +// userinfo. The server applies them too; checking here refuses a bad id +// before the CLI tries to claim it. +func checkExternalID(id string) error { + if id == "" || utf8.RuneCountInString(id) > 512 { + return errors.New("an external id is 1 to 512 characters") + } + for _, r := range id { + if unicode.IsSpace(r) || unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return errors.New("an external id has no whitespace, control or invisible format characters") + } + } + if u, err := url.Parse(id); err == nil && u.User != nil { + return errors.New("an external id carries no userinfo") + } + return nil +} + +// oneLine makes outside text safe for one line of a terminal or a message: +// control and invisible format characters become spaces, runs of spaces +// collapse, and it is cut to max runes. +func oneLine(s string, max int) string { + var b strings.Builder + space := false + n := 0 + for _, r := range s { + if r == utf8.RuneError || unicode.IsControl(r) || unicode.Is(unicode.Cf, r) || unicode.IsSpace(r) { + if !space && b.Len() > 0 { + b.WriteByte(' ') + } + space = true + continue + } + if n == max { + b.WriteString("…") + break + } + b.WriteRune(r) + space = false + n++ + } + return strings.TrimSpace(b.String()) +} + +// boundTitle keeps a title inside the runner's 1024-byte bound, cutting on a +// character boundary. GitHub's own 256-character limit keeps real titles far +// inside it. +func boundTitle(s string) string { + const max = 1000 + if len(s) <= max { + return s + } + cut := max + for cut > 0 && !utf8.RuneStart(s[cut]) { + cut-- + } + return s[:cut] + "…" +} diff --git a/internal/fakegithub/fakegithub.go b/internal/fakegithub/fakegithub.go new file mode 100644 index 0000000..a2ce945 --- /dev/null +++ b/internal/fakegithub/fakegithub.go @@ -0,0 +1,449 @@ +// Package fakegithub is an in-memory stand-in for the slice of the GitHub API +// the adapter uses: the GraphQL issue list and issue read, and the REST label, +// comment, rate-limit and repository endpoints. It exists for the adapter's +// own tests and its conformance suite; it is not a general GitHub fake. +package fakegithub + +import ( + "encoding/base64" + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" + "sort" + "strconv" + "strings" + "sync" + "time" +) + +// Issue is one issue of a fake repository. +type Issue struct { + Number int + Title string + Body string + State string // OPEN or CLOSED + CreatedAt time.Time + Labels []string +} + +// Comment is a comment the adapter posted. +type Comment struct { + Repo string // owner/name as the request spelled it + Number int + Body string +} + +// Server is a fake GitHub. Its methods are safe for concurrent use. +type Server struct { + *httptest.Server + + // Token is the only credential the fake accepts ("Bearer "). + Token string + + mu sync.Mutex + // repos is keyed by the lower-cased "owner/name"; canon keeps GitHub's + // own spelling, which is what an issue URL carries. + repos map[string][]*Issue + canon map[string]string + fail map[string]int // lower-cased "owner/name" -> HTTP status for any read of it + // repoLabels are the labels defined in a repository (not on an issue). + repoLabels map[string][]string + echo string // when set, error bodies carry this text (to test redaction) + // cursorPad lengthens every issue cursor to at least this many bytes + // (GitHub's cursors are opaque and their length is not promised). + cursorPad int + // urlSuffix is appended to every issue URL in a list (a misbehaving proxy). + urlSuffix string + // commentFail, when set, answers every comment POST with this status + // (the label POST before it still succeeds). + commentFail int + Comments []Comment + Requests []string // "METHOD path" or "GRAPHQL op", in order +} + +// New starts a fake GitHub that accepts token. +func New(token string) *Server { + s := &Server{Token: token, repos: map[string][]*Issue{}, canon: map[string]string{}, fail: map[string]int{}, repoLabels: map[string][]string{}} + s.Server = httptest.NewServer(http.HandlerFunc(s.serve)) + return s +} + +// AddRepo creates a repository spelled as GitHub spells it ("Owner/Name"). +func (s *Server) AddRepo(full string, issues ...Issue) { + s.mu.Lock() + defer s.mu.Unlock() + k := strings.ToLower(full) + s.canon[k] = full + for i := range issues { + is := issues[i] + if is.State == "" { + is.State = "OPEN" + } + s.repos[k] = append(s.repos[k], &is) + } +} + +// DefineLabel creates a label in a repository's label list. +func (s *Server) DefineLabel(full, label string) { + s.mu.Lock() + defer s.mu.Unlock() + k := strings.ToLower(full) + s.repoLabels[k] = append(s.repoLabels[k], label) +} + +// Fail makes every read of a repository answer with status. +func (s *Server) Fail(full string, status int) { + s.mu.Lock() + defer s.mu.Unlock() + s.fail[strings.ToLower(full)] = status +} + +// FailComments makes every comment POST answer with status. +func (s *Server) FailComments(status int) { + s.mu.Lock() + defer s.mu.Unlock() + s.commentFail = status +} + +// EchoInErrors makes error bodies include text, as a misbehaving proxy might. +func (s *Server) EchoInErrors(text string) { + s.mu.Lock() + defer s.mu.Unlock() + s.echo = text +} + +// PadCursors makes every issue cursor at least n bytes long. +func (s *Server) PadCursors(n int) { + s.mu.Lock() + defer s.mu.Unlock() + s.cursorPad = n +} + +// SuffixURLs appends text to every issue URL a list returns. +func (s *Server) SuffixURLs(text string) { + s.mu.Lock() + defer s.mu.Unlock() + s.urlSuffix = text +} + +// Labels returns an issue's current labels. +func (s *Server) Labels(full string, number int) []string { + s.mu.Lock() + defer s.mu.Unlock() + if is := s.find(strings.ToLower(full), number); is != nil { + return append([]string(nil), is.Labels...) + } + return nil +} + +// SetLabels replaces an issue's labels (a teammate relabelling by hand). +func (s *Server) SetLabels(full string, number int, labels ...string) { + s.mu.Lock() + defer s.mu.Unlock() + if is := s.find(strings.ToLower(full), number); is != nil { + is.Labels = append([]string(nil), labels...) + } +} + +// IssueURL is the canonical issue URL GitHub would print. +func (s *Server) IssueURL(full string, number int) string { + s.mu.Lock() + defer s.mu.Unlock() + return fmt.Sprintf("https://github.com/%s/issues/%d", s.canon[strings.ToLower(full)], number) +} + +func (s *Server) find(k string, number int) *Issue { + for _, is := range s.repos[k] { + if is.Number == number { + return is + } + } + return nil +} + +func (s *Server) record(r string) { + s.Requests = append(s.Requests, r) +} + +func (s *Server) writeErr(w http.ResponseWriter, status int, msg string) { + if s.echo != "" { + msg += " " + s.echo + } + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(map[string]string{"message": msg}) +} + +func writeJSON(w http.ResponseWriter, status int, v any) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(v) +} + +func (s *Server) serve(w http.ResponseWriter, r *http.Request) { + s.mu.Lock() + defer s.mu.Unlock() + if r.Header.Get("Authorization") != "Bearer "+s.Token { + s.record("UNAUTHORIZED " + r.URL.Path) + s.writeErr(w, http.StatusUnauthorized, "Bad credentials") + return + } + if r.Method == http.MethodPost && r.URL.Path == "/graphql" { + s.graphql(w, r) + return + } + s.record(r.Method + " " + r.URL.Path) + if r.URL.Path == "/rate_limit" && r.Method == http.MethodGet { + writeJSON(w, 200, map[string]any{"resources": map[string]any{"core": map[string]int{"remaining": 4999}}}) + return + } + parts := strings.Split(strings.TrimPrefix(r.URL.Path, "/"), "/") + if len(parts) < 3 || parts[0] != "repos" { + s.writeErr(w, 404, "Not Found") + return + } + k := strings.ToLower(parts[1] + "/" + parts[2]) + if st := s.fail[k]; st != 0 { + s.writeErr(w, st, "Server Error") + return + } + if _, ok := s.canon[k]; !ok { + s.writeErr(w, 404, "Not Found") + return + } + if len(parts) == 3 && r.Method == http.MethodGet { + writeJSON(w, 200, map[string]any{"full_name": s.canon[k]}) + return + } + if len(parts) == 5 && parts[3] == "labels" && r.Method == http.MethodGet { + for _, l := range s.repoLabels[k] { + if strings.EqualFold(l, parts[4]) { + writeJSON(w, 200, map[string]string{"name": l}) + return + } + } + s.writeErr(w, 404, "Not Found") + return + } + if len(parts) < 6 || parts[3] != "issues" { + s.writeErr(w, 404, "Not Found") + return + } + n, err := strconv.Atoi(parts[4]) + is := s.find(k, n) + if err != nil || is == nil { + s.writeErr(w, 404, "Not Found") + return + } + switch { + case parts[5] == "labels" && len(parts) == 6 && r.Method == http.MethodGet: + per, _ := strconv.Atoi(r.URL.Query().Get("per_page")) + page, _ := strconv.Atoi(r.URL.Query().Get("page")) + if per <= 0 { + per = 30 + } + if page <= 0 { + page = 1 + } + out := []map[string]string{} + for i := (page - 1) * per; i < len(is.Labels) && i < page*per; i++ { + out = append(out, map[string]string{"name": is.Labels[i]}) + } + writeJSON(w, 200, out) + case parts[5] == "labels" && len(parts) == 6 && r.Method == http.MethodPost: + var body struct { + Labels []string `json:"labels"` + } + if json.NewDecoder(r.Body).Decode(&body) != nil { + s.writeErr(w, 422, "Invalid request") + return + } + for _, l := range body.Labels { + if !hasFold(is.Labels, l) { + is.Labels = append(is.Labels, l) + } + } + writeJSON(w, 200, labelObjs(is.Labels)) + case parts[5] == "labels" && len(parts) == 7 && r.Method == http.MethodDelete: + name := parts[6] + kept := is.Labels[:0:0] + found := false + for _, l := range is.Labels { + if strings.EqualFold(l, name) { + found = true + continue + } + kept = append(kept, l) + } + if !found { + s.writeErr(w, 404, "Label does not exist") + return + } + is.Labels = kept + writeJSON(w, 200, labelObjs(is.Labels)) + case parts[5] == "comments" && len(parts) == 6 && r.Method == http.MethodPost: + if s.commentFail != 0 { + s.writeErr(w, s.commentFail, "comment refused") + return + } + var body struct { + Body string `json:"body"` + } + b, _ := io.ReadAll(r.Body) + if json.Unmarshal(b, &body) != nil || body.Body == "" { + s.writeErr(w, 422, "Invalid request") + return + } + s.Comments = append(s.Comments, Comment{Repo: parts[1] + "/" + parts[2], Number: n, Body: body.Body}) + writeJSON(w, 201, map[string]any{"id": len(s.Comments)}) + default: + s.writeErr(w, 404, "Not Found") + } +} + +func hasFold(list []string, v string) bool { + for _, l := range list { + if strings.EqualFold(l, v) { + return true + } + } + return false +} + +func labelObjs(ls []string) []map[string]string { + out := []map[string]string{} + for _, l := range ls { + out = append(out, map[string]string{"name": l}) + } + return out +} + +func (s *Server) cursor(number int) string { + raw := "cursor:v2:" + strconv.Itoa(number) + if s.cursorPad > 0 { + raw += "|" + for len(base64.StdEncoding.EncodeToString([]byte(raw))) < s.cursorPad { + raw += "x" + } + } + return base64.StdEncoding.EncodeToString([]byte(raw)) +} + +type gqlReq struct { + Query string `json:"query"` + OperationName string `json:"operationName"` + Variables map[string]any `json:"variables"` +} + +func str(v any) string { + s, _ := v.(string) + return s +} + +func num(v any) int { + f, _ := v.(float64) + return int(f) +} + +func labelConn(labels []string, first int) map[string]any { + nodes := []map[string]string{} + for i := 0; i < len(labels) && i < first; i++ { + nodes = append(nodes, map[string]string{"name": labels[i]}) + } + return map[string]any{"nodes": nodes, "pageInfo": map[string]bool{"hasNextPage": len(labels) > first}} +} + +func (s *Server) graphql(w http.ResponseWriter, r *http.Request) { + var q gqlReq + if err := json.NewDecoder(r.Body).Decode(&q); err != nil { + s.writeErr(w, 400, "Problems parsing JSON") + return + } + s.record("GRAPHQL " + q.OperationName) + owner, name := str(q.Variables["owner"]), str(q.Variables["name"]) + k := strings.ToLower(owner + "/" + name) + if st := s.fail[k]; st != 0 { + s.writeErr(w, st, "Server Error") + return + } + full, ok := s.canon[k] + if !ok { + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": nil}, + "errors": []map[string]string{{"type": "NOT_FOUND", "message": fmt.Sprintf("Could not resolve to a Repository with the name '%s'.", owner+"/"+name)}}}) + return + } + labelsFirst := num(q.Variables["labelsFirst"]) + if labelsFirst <= 0 { + labelsFirst = 100 + } + switch q.OperationName { + case "ListOpenIssues": + open := []*Issue{} + for _, is := range s.repos[k] { + if is.State == "OPEN" { + open = append(open, is) + } + } + sort.SliceStable(open, func(i, j int) bool { + if !open[i].CreatedAt.Equal(open[j].CreatedAt) { + return open[i].CreatedAt.Before(open[j].CreatedAt) + } + return open[i].Number < open[j].Number + }) + start := 0 + if after := str(q.Variables["after"]); after != "" { + raw, err := base64.StdEncoding.DecodeString(after) + pos, _, _ := strings.Cut(strings.TrimPrefix(string(raw), "cursor:v2:"), "|") + n, err2 := strconv.Atoi(pos) + if err != nil || err2 != nil { + writeJSON(w, 200, map[string]any{"errors": []map[string]string{{"message": "`" + after + "` does not appear to be a valid cursor."}}}) + return + } + // GitHub's cursor names a position, not an issue: resume after + // the issue with that number in the current order. + start = len(open) + for i, is := range open { + if is.Number == n { + start = i + 1 + break + } + } + } + first := num(q.Variables["first"]) + edges := []map[string]any{} + end := start + for i := start; i < len(open) && len(edges) < first; i++ { + is := open[i] + edges = append(edges, map[string]any{ + "cursor": s.cursor(is.Number), + "node": map[string]any{ + "number": is.Number, "title": is.Title, + "url": fmt.Sprintf("https://github.com/%s/issues/%d", full, is.Number) + s.urlSuffix, + "createdAt": is.CreatedAt.UTC().Format(time.RFC3339), + "labels": labelConn(is.Labels, labelsFirst), + }, + }) + end = i + 1 + } + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": map[string]any{"issues": map[string]any{ + "edges": edges, + "pageInfo": map[string]any{"hasNextPage": end < len(open)}, + }}}}) + case "GetIssue": + is := s.find(k, num(q.Variables["number"])) + if is == nil { + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": map[string]any{"issue": nil}}, + "errors": []map[string]string{{"type": "NOT_FOUND", "message": "Could not resolve to an Issue."}}}) + return + } + writeJSON(w, 200, map[string]any{"data": map[string]any{"repository": map[string]any{"issue": map[string]any{ + "number": is.Number, "title": is.Title, "body": is.Body, "state": is.State, + "url": fmt.Sprintf("https://github.com/%s/issues/%d", full, is.Number), + "labels": labelConn(is.Labels, labelsFirst), + }}}}) + default: + writeJSON(w, 200, map[string]any{"errors": []map[string]string{{"message": "unknown operation " + q.OperationName}}}) + } +}