dev/linearhooks: add POC (#62367)

Author: michaellzc

.gitattributes

@@ -8,3 +8,4 @@ cmd/repo-updater/repos/testdata/** linguist-generated=true
 CHANGELOG.md merge=union
 **/mocks*_*test.go linguist-generated=true
 .apko/range.sh linguist-generated=true
+dev/linearhooks/internal/lineargql/gqltest/fake_client.go

.prettierignore

@@ -62,3 +62,6 @@ client/browser/src/types/webextension-polyfill/index.d.ts
 graphql-operations.ts
 
 wolfi-images/*.lock.json
+
+# This is downloaded from upstream directly and should not be modified
+dev/linearhooks/internal/lineargql/schema.graphql

deps.bzl

@@ -3142,8 +3142,8 @@ def go_dependencies():
         name = "com_github_hashicorp_golang_lru_v2",
         build_file_proto_mode = "disable_global",
         importpath = "github.com/hashicorp/golang-lru/v2",
-        sum = "h1:Dwmkdr5Nc/oBiXgJS3CDHNhJtIHkuZ3DZF5twqnfBdU=",
-        version = "v2.0.2",
+        sum = "h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=",
+        version = "v2.0.7",
     )
     go_repository(
         name = "com_github_hashicorp_hcl",
@@ -4188,6 +4188,13 @@ def go_dependencies():
         sum = "h1:jWpvCLoY8Z/e3VKvlsiIGKtc+UG6U5vzxaoagmhXfyg=",
         version = "v2.0.0",
     )
+    go_repository(
+        name = "com_github_maxbrunsfeld_counterfeiter_v6",
+        build_file_proto_mode = "disable_global",
+        importpath = "github.com/maxbrunsfeld/counterfeiter/v6",
+        sum = "h1:NicmruxkeqHjDv03SfSxqmaLuisddudfP3h5wdXFbhM=",
+        version = "v6.8.1",
+    )
     go_repository(
         name = "com_github_mazznoer_csscolorparser",
         build_file_proto_mode = "disable_global",
@@ -5240,6 +5247,13 @@ def go_dependencies():
         sum = "h1:QGadEcsmypxg8gYChRSM2j1edLyE/2j72j+hdmI4BJM=",
         version = "v2.2.0",
     )
+    go_repository(
+        name = "com_github_sclevine_spec",
+        build_file_proto_mode = "disable_global",
+        importpath = "github.com/sclevine/spec",
+        sum = "h1:z/Q9idDcay5m5irkZ28M7PtQM4aOISzOpj4bUPkDee8=",
+        version = "v1.4.0",
+    )
     go_repository(
         name = "com_github_sean_seed",
         build_file_proto_mode = "disable_global",

dev/linearhooks/.env.example

@@ -0,0 +1,7 @@
+export CONFIG_FILE_PATH=config.example.yaml
+export LINEAR_PERSONAL_API_KEY=
+export LINEAR_WEBHOOK_SIGNING_SECRET=
+export PORT=3000
+export SRC_DEVELOPMENT=true
+export SRC_LOG_FORMAT=console
+export SRC_LOG_LEVEL=debug

dev/linearhooks/BUILD.bazel

@@ -0,0 +1,62 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
+load("//dev:oci_defs.bzl", "image_repository", "oci_image", "oci_push", "oci_tarball")
+load("@rules_pkg//:pkg.bzl", "pkg_tar")
+load("@container_structure_test//:defs.bzl", "container_structure_test")
+
+go_library(
+    name = "linearhooks_lib",
+    srcs = ["main.go"],
+    importpath = "github.com/sourcegraph/sourcegraph/dev/linearhooks",
+    visibility = ["//visibility:private"],
+    deps = [
+        "//dev/linearhooks/internal/service",
+        "//lib/managedservicesplatform/runtime",
+    ],
+)
+
+go_binary(
+    name = "linearhooks",
+    embed = [":linearhooks_lib"],
+    visibility = ["//visibility:public"],
+)
+
+pkg_tar(
+    name = "tar_linearhooks",
+    srcs = [":linearhooks"],
+)
+
+oci_image(
+    name = "image",
+    base = "@wolfi_base",
+    entrypoint = [
+        "/sbin/tini",
+        "--",
+        "/linearhooks",
+    ],
+    tars = [":tar_linearhooks"],
+    user = "sourcegraph",
+)
+
+oci_tarball(
+    name = "image_tarball",
+    image = ":image",
+    repo_tags = ["linearhooks:candidate"],
+)
+
+container_structure_test(
+    name = "image_test",
+    timeout = "short",
+    configs = ["image_test.yaml"],
+    driver = "docker",
+    image = ":image",
+    tags = [
+        "exclusive",
+        "requires-network",
+    ],
+)
+
+oci_push(
+    name = "candidate_push",
+    image = ":image",
+    repository = image_repository("linearhooks"),
+)

dev/linearhooks/README.md

@@ -0,0 +1,43 @@
+# Linear Webhooks
+
+## Development
+
+> [!CAUTION]
+> DO NOT commit your api key
+
+First make a copy of the dotenv file and set the API key and webhook signing secrets in `.env` based on the [Linear API settings](https://linear.app/sourcegraph/settings/api). If you don't have access, reach out to #wg-linear-trial.
+
+```sh
+cp .env.example .env
+```
+
+```sh
+source .env
+```
+
+```sh
+go run .
+```
+
+Use [ngrok](https://ngrok.com/docs/getting-started/) to get a public URL for receiving webhook events:
+
+```sh
+ngrok http 3000
+```
+
+Set the [webhook URL in Linear](https://linear.app/sourcegraph/settings/api).
+
+## Deployment
+
+This service is deployed as a MSP service. Learn more from [go/msp](http://go/msp).
+
+> [!CAUTION]
+> Keep your secret safe
+
+In production, it's recommended to create a [Linear OAuth2 application](https://developers.linear.app/docs/oauth/authentication), and create a developer token using application identity as actor. Then, set the developer token as `LINEAR_PERSONAL_API_KEY` in the deployment. Othewise, your personal identity will be associated with all requests.
+
+Unfortunately, Linear only supports `authorization_code` grant type, but not `client_credentials`. Authenticating through the web interface (e.g., OAuth callback) is a lot of added complexity for a simply webhook service. We will revisit in the future.
+
+## Configuration
+
+Refer to [config.example.yaml](./config.example.yaml)

dev/linearhooks/config.example.yaml

@@ -0,0 +1,15 @@
+spec:
+  mover:
+    # rules is a list of rules that define the conditions for moving issues between teams
+    # Only the first rule that matches the issue will be applied, the rest will be ignored
+    rules:
+      - src:
+          # teamId is the identifier of the source team. Only issues from this team will be evaluated for this rule
+          # Either identifier (i.e. unique team prefix) or UUID is accepted. Use 'Any Team' to match any incoming team.
+          teamId: FOO
+          # labels is a list of labels that the issue must have to be evaluated for this rule
+          labels: [team/bar]
+        dst:
+          # teamId is the identifier of the destination team. Issues that match the rule will be moved to this team.
+          # Either identifier (i.e. unique team prefix) or UUID is accepted
+          teamId: BAR

dev/linearhooks/image_test.yaml

@@ -0,0 +1,14 @@
+schemaVersion: '2.0.0'
+
+commandTests:
+  - name: 'binary is runnable'
+    command: '/linearhooks'
+    args:
+      - '--help'
+
+  - name: 'not running as root'
+    command: '/usr/bin/id'
+    args:
+      - -u
+    excludedOutput: ['^0']
+    exitCode: 0

dev/linearhooks/internal/handlers/BUILD.bazel

@@ -0,0 +1,38 @@
+load("//dev:go_defs.bzl", "go_test")
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "handlers",
+    srcs = [
+        "config.go",
+        "handlers.go",
+        "middleware.go",
+    ],
+    importpath = "github.com/sourcegraph/sourcegraph/dev/linearhooks/internal/handlers",
+    visibility = ["//dev/linearhooks:__subpackages__"],
+    deps = [
+        "//dev/linearhooks/internal/lineargql",
+        "//dev/linearhooks/internal/linearschema",
+        "//internal/collections",
+        "//lib/errors",
+        "@com_github_hashicorp_golang_lru_v2//expirable",
+        "@com_github_khan_genqlient//graphql",
+        "@com_github_sourcegraph_log//:log",
+        "@io_k8s_sigs_yaml//:yaml",
+    ],
+)
+
+go_test(
+    name = "handlers_test",
+    srcs = ["handlers_test.go"],
+    embed = [":handlers"],
+    deps = [
+        "//dev/linearhooks/internal/lineargql",
+        "//dev/linearhooks/internal/lineargql/gqltest",
+        "//dev/linearhooks/internal/linearschema",
+        "@com_github_hexops_autogold_v2//:autogold",
+        "@com_github_sourcegraph_log//logtest",
+        "@com_github_stretchr_testify//assert",
+        "@com_github_stretchr_testify//require",
+    ],
+)

dev/linearhooks/internal/handlers/config.go

@@ -0,0 +1,71 @@
+package handlers
+
+import (
+	"github.com/sourcegraph/sourcegraph/lib/errors"
+)
+
+type Config struct {
+	Spec Spec `json:"spec"`
+}
+
+type Spec struct {
+	Mover MoverSpec `json:"mover,omitempty"`
+}
+
+type MoverSpec struct {
+	Rules []RuleSpec `json:"rules"`
+}
+
+type RuleSpec struct {
+	// Src is the identifier of the source team. Only issues from this team will be evaluated for this rule.
+	Src SrcSpec `json:"src"`
+	// Dst is the identifier of the destination team. Issues that match the rule will be moved to this team.
+	Dst DstSpec `json:"dst"`
+}
+
+type SrcSpec struct {
+	// TeamID is the identifier of the team that the issue must be in for the rule to match.
+	// Use the keyword 'Any Issue' to match any source team.
+	TeamID string `json:"teamId,omitempty"`
+	// Labels is a list of labels that must be present on the issue for the rule to match.
+	Labels []string `json:"labels"`
+}
+
+type DstSpec struct {
+	TeamID string `json:"teamId,omitempty"`
+}
+
+func (c *Config) Validate() error {
+	return c.Spec.Validate()
+}
+
+func (s *Spec) Validate() error {
+	return s.Mover.Validate()
+}
+
+func (s *MoverSpec) Validate() error {
+	var errs errors.MultiError
+	if len(s.Rules) == 0 {
+		errs = errors.Append(errs, errors.New("rules must contain at least one rule"))
+	}
+	for _, r := range s.Rules {
+		if err := r.Validate(); err != nil {
+			errs = errors.Append(errs, err)
+		}
+	}
+	return errs
+}
+
+func (rs RuleSpec) Validate() error {
+	var errs errors.MultiError
+	if rs.Src.TeamID == "" {
+		errs = errors.Append(errs, errors.Newf("src.teamId must be set, or use %d to match any issues", WildcardTeamID))
+	}
+	if len(rs.Src.Labels) == 0 {
+		errs = errors.Append(errs, errors.New("src.labels must contain at least one label"))
+	}
+	if rs.Dst.TeamID == "" {
+		errs = errors.Append(errs, errors.New("dst.teamId must be set"))
+	}
+	return errs
+}