feature: rework api

.github/workflows/trigger-api-go-update.yml

@@ -0,0 +1,61 @@
+name: 'Trigger api-go Update'
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch in api-go repo to trigger update protos (default: master)"
+        required: true
+        default: master
+
+jobs:
+  notify:
+    name: 'Trigger api-go update'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Generate token
+        id: generate_token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.RR_CICD_APP_ID }}
+          private-key: ${{ secrets.RR_CICD_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: api-go
+
+      - name: Dispatch api-go Github Action
+        env:
+          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+          EVENT_PUSH_BRANCH: ${{ github.event.ref }}
+          EVENT_PUSH_COMMIT_AUTHOR: ${{ github.event.head_commit.author.name }}
+          EVENT_PUSH_COMMIT_AUTHOR_EMAIL: ${{ github.event.head_commit.author.email }}
+          EVENT_PUSH_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+          EVENT_WF_DISPATCH_BRANCH: ${{ github.event.inputs.branch }}
+        run: |
+          case "${{ github.event_name }}" in
+            "push")
+              BRANCH="${EVENT_PUSH_BRANCH#refs/heads/}"
+              COMMIT_AUTHOR="${EVENT_PUSH_COMMIT_AUTHOR}"
+              COMMIT_AUTHOR_EMAIL="${EVENT_PUSH_COMMIT_AUTHOR_EMAIL}"
+              COMMIT_MESSAGE="${EVENT_PUSH_COMMIT_MESSAGE}"
+              ;;
+            "workflow_dispatch")
+              BRANCH="${EVENT_WF_DISPATCH_BRANCH}"
+              COMMIT_AUTHOR="RoadRunner Bot"
+              COMMIT_AUTHOR_EMAIL="bot@roadrunner.dev"
+              COMMIT_MESSAGE="Update proto"
+              ;;
+          esac
+
+          gh workflow run update-proto.yml \
+            -R roadrunner-server/api-go \
+            -r master \
+            -f branch="${BRANCH}" \
+            -f commit_author="${COMMIT_AUTHOR}" \
+            -f commit_author_email="${COMMIT_AUTHOR_EMAIL}" \
+            -f commit_message="${COMMIT_MESSAGE}"

README.md

@@ -16,29 +16,65 @@
 
 # RoadRunner API
 
-To install and use generated packages:
+This repository contains the **Protocol Buffer definitions** for [RoadRunner](https://roadrunner.dev). These protos are used for external integrations (RPC) and internal communications between RoadRunner plugins.
+
+Generated Go code lives in a separate repository: [`roadrunner-server/api-go`](https://github.com/roadrunner-server/api-go).
+
+## Repository structure
+
+```
+roadrunner/api/   — RoadRunner proto definitions (jobs, kv, http, status, etc.)
+third_party/api/  — Temporal API submodule (used as a proto dependency)
+buf.yaml          — Buf module configuration
+buf.gen.yaml      — Buf code generation configuration
+```
+
+## Using generated Go packages
+
+Install a package from the [`api-go`](https://github.com/roadrunner-server/api-go) repository:
 ```bash
-go get github.com/roadrunner-server/api/v4/build/<API_NAME>/v1
+go get github.com/roadrunner-server/api-go/v5/build/<module>/<version>
 ```
 
-The Proto API is used for external integrations, mostly for RPC or as internal communications. For example:
+Example usage:
 ```go
 package foo
 
 import (
-	jobsv1 "github.com/roadrunner-server/api/v4/build/jobs/v1"
+	jobsv1 "github.com/roadrunner-server/api-go/v5/build/jobs/v1"
 )
 
 func Push(in *jobsv1.PushRequest, out *jobsv1.Empty) error {
 	return nil
 }
 ```
 
-# Centrifugal API
-- [API](https://github.com/centrifugal/centrifugo/blob/master/internal/apiproto/api.proto)
-- [Proxy](https://github.com/centrifugal/centrifugo/blob/master/internal/proxyproto/proxy.proto)
+## Auto-generation
+
+Pushing to `master` in this repo triggers a GitHub Actions workflow in [`api-go`](https://github.com/roadrunner-server/api-go) that:
+1. Pulls the latest proto definitions via a git submodule.
+2. Runs `buf generate` to produce Go code.
+3. Commits and pushes the result.
+
+You do not need to run code generation manually — CI handles it automatically.
 
-# Building API
+## Local development
 
-- Install buf:  `go install github.com/bufbuild/buf/cmd/buf@latest`.
-- In the repository root run: `buf generate --debug`
+Install [Buf](https://buf.build/docs/installation):
+```bash
+go install github.com/bufbuild/buf/cmd/buf@latest
+```
+
+Lint proto files:
+```bash
+buf lint
+```
+
+Generate code locally (output goes to `build/`):
+```bash
+buf generate
+```
+
+## Centrifugal API
+- [API](https://github.com/centrifugal/centrifugo/blob/master/internal/apiproto/api.proto)
+- [Proxy](https://github.com/centrifugal/centrifugo/blob/master/internal/proxyproto/proxy.proto)

buf.yaml

@@ -1,11 +1,10 @@
 version: v2
 modules:
-    - path: proto
+    - path: roadrunner/api
     - path: third_party/api
 lint:
     disallow_comment_ignores: true
     ignore:
-        # This is a third-party API, so we ignore them for linters.
         - third_party/api
-        - proto/centrifugo/api
-        - proto/centrifugo/proxy
+        - roadrunner/api/centrifugo/api
+        - roadrunner/api/centrifugo/proxy