0017 SCM Provider Abstraction

github_repo_connections
  installation_id       bigint
  repository_id         bigint
  repository_full_name  varchar
  app_id (unique), project_id, workspace_id, timestamps
  index on (installation_id)

repo_connections
  id                    varchar    -- uid.New("conn"), the {connection_id} in the webhook path
  provider              ENUM('github','gitlab','bitbucket','gitea') NOT NULL,
  provider_host         varchar    -- set for self-hosted, null for cloud providers
  provider_repo_id      varchar    -- some providers use string compared to GH's int. GH can stringify and store it here
  provider_hook_id      varchar    -- the hook id the provider gave us, to update or delete it later. empty for GH
  installation_id       bigint     -- GH needs it
  repository_full_name  varchar
  provider_token        text       -- vault-encrypted. empty for GH, long-lived token or Bitbucket rotating refresh token
  app_id (unique), project_id, workspace_id, timestamps

type Provider interface {
    Descriptor() Descriptor // what the provider needs, connect style and webhook scope

    // connect flow, every provider does these
    ListRepos(ctx context.Context, sess Session) ([]Repo, error)
    // CreateHook returns the provider's hook id, we store it so we can delete it on disconnect
    CreateHook(ctx context.Context, sess Session, repo RepoID, hookURL, secret string) (hookID string, err error)
    // UpdateHook rewrites the URL and the secret of a hook we already created, for key rotation
    UpdateHook(ctx context.Context, conn Connection, hookID, hookURL, secret string) error
    DeleteHook(ctx context.Context, conn Connection, hookID string) error

    // today: pkg/webhook/verifiers/github
    // secrets holds the connection's signing keys, newest first
    VerifyWebhook(r *http.Request, secrets []string) (Event, error)
    // today: the parsing half of svc/ctrl/api/webhooks/github
    ParsePush(event Event) (PushInfo, error)

    // today: GetScopedInstallationToken in worker deploy/build.go
    CloneCredential(ctx context.Context, conn Connection) (Credential, error)

    // today: the GitHubClient interface in pkg/github
    Client(creds Credential) Client
}

// oauth providers (gitlab, bitbucket) also implement this
type OAuthConnector interface {
    AuthorizeURL(state string) string
    ExchangeCode(ctx context.Context, code string) (token string, err error)
}

// token+url providers (gitea) implement this instead
type TokenConnector interface {
    Validate(ctx context.Context, instanceURL, token string) error
}

type Descriptor struct {
    ConnectStyle        ConnectStyle
    WebhookScope        WebhookScope
    NeedsWorkspaceInput bool // Bitbucket: ask workspace slug
    NeedsInstanceURL    bool // Gitea: ask "where is your server?"
}

switch (descriptor.connectStyle) {
  case "app_install":
    return <InstallRedirect provider={provider} />;
  case "oauth":
    return <OAuthButton provider={provider} />;
  case "token+url":
    return (
      <TokenForm
        askInstanceURL={descriptor.needsInstanceURL}
        askWorkspace={descriptor.needsWorkspaceInput}
      />
    );
}

// pkg/scm
var registry = map[string]Provider{}

func Register(name string, p Provider) {
    registry[name] = p
}

func Registered() map[string]Provider {
    return registry
}

scm.Register("github", github.New(cfg.GitHub, store))
scm.Register("gitlab", gitlab.New(cfg.GitLab, store))
scm.Register("bitbucket", bitbucket.New(cfg.Bitbucket, store))
scm.Register("gitea", gitea.New(cfg.Gitea, store))

for name, p := range scm.Registered() {
    switch p.Descriptor().WebhookScope {
    case scm.WebhookScopeAppGlobal: // GitHub only
        mux.Handle("POST /webhooks/"+name, appGlobalHandler(p))
    case scm.WebhookScopePerConnection:
        // v1 leads the path, it is the route shape version, explained in "Webhook ingress" below
        mux.Handle("POST /v1/webhooks/"+name+"/{connection_id}", perConnectionHandler(p))
    }
}

type ConnectStyle string

const (
    ConnectStyleAppInstall ConnectStyle = "app_install" // Github
    ConnectStyleOAuth      ConnectStyle = "oauth"       // GitLab, Bitbucket
    ConnectStyleTokenURL   ConnectStyle = "token+url"   // Gitea
)

type WebhookScope string

const (
    WebhookScopeAppGlobal     WebhookScope = "app_global"     // Github only
    WebhookScopePerConnection WebhookScope = "per_connection" // everyone else
)

enum ConnectStyle {
  CONNECT_STYLE_UNSPECIFIED = 0;
  CONNECT_STYLE_APP_INSTALL = 1;
  CONNECT_STYLE_OAUTH = 2;
  CONNECT_STYLE_TOKEN_URL = 3;
}

message ProviderDescriptor {
  string provider = 1;             // "github" | "gitlab" | "bitbucket" | "gitea"
  ConnectStyle connect_style = 2;
  bool needs_workspace_input = 3;
  bool needs_instance_url = 4;
}

rpc ListProviders(ListProvidersRequest) returns (ListProvidersResponse);

providers: t.procedure.query(() => ctrl.scmConnect.listProviders());
// OR
api.scm.listProviders(); // Not the final shape

const PROVIDERS: Record<string, ProviderDescriptor> = {
  github: {
    connectStyle: "app_install",
    needsWorkspaceInput: false,
    needsInstanceURL: false,
  },
  gitlab: {
    connectStyle: "oauth",
    needsWorkspaceInput: false,
    needsInstanceURL: false,
  },
  bitbucket: {
    connectStyle: "oauth",
    needsWorkspaceInput: true,
    needsInstanceURL: false,
  },
  gitea: {
    connectStyle: "token+url",
    needsWorkspaceInput: false,
    needsInstanceURL: true,
  },
};

service ScmConnectService {
  rpc Start(...)         returns (...);  // oauth: authorize URL + signed state
  rpc Callback(...)      returns (...);  // oauth: code -> session
  rpc Validate(...)      returns (...);  // token+url: creds -> session
  rpc ListRepos(...)     returns (...);  // session -> picker data
  rpc Complete(...)      returns (...);  // session + repo + app -> hook + connection row
  rpc Disconnect(...)    returns (...);  // connectionId -> delete hook, then drop the row and its keys
}

scm_connect_sessions
  id             varchar     -- uid.New("scs"), the only thing the browser holds
  workspace_id   varchar
  provider       ENUM('github','gitlab','bitbucket','gitea') NOT NULL, -- github never creates a session
  provider_host  varchar     -- set for self-hosted, null for cloud providers
  token          text        -- vault-encrypted, never leaves ctrl
  consumed       boolean     -- complete is single-use
  expires_at     bigint      -- ~30min TTL
  created_at     bigint

scm_webhook_keys
  id             varchar   -- uid.New("swk")
  connection_id  varchar   -- the repo_connections row this key belongs to
  secret         text      -- vault-encrypted, 32 random bytes
  created_at     bigint
  index on (connection_id)