В этом посте я покажу, как с помощью GitHub Actions легко реализовать генерацию и публикацию gRPC API пакетов в GitHub Packages, в реестрах Apache Maven и npm. Если вы хотите освоить GitHub Packages для своих проектов и научиться генерировать gRPC API для сервисов на Kotlin/Java и gRPC-web клиентов — добро пожаловать под кат.

Введение

Во время подготовки к докладу JPoint у меня возникла идея создать тестовый стенд, включающий веб-клиент и бэкенд-приложение. Этот стенд позволил бы наглядно демонстрировать эффективность различных стратегий выполнения SQL-запросов с пагинацией. Для взаимодействия между клиентом и бэкендом я решил использовать gRPC. Мне показалась интересной такая реализация взаимодействия между сервером и веб-клиентом, а также генерация и публикация gRPC API пакетов с помощью GitHub Actions и GitHub Packages. Поэтому я решил поделиться этим опытом с читателями Хабра.

Выбор технологического стека и особенности

Для реализации я использовал Kotlin, однако все представленные здесь примеры также могут быть адаптированы для Java.

Я выбрал Spring и Kotlin для бэкенда, а также React с TypeScript для клиентской части, что облегчило реализацию нужного функционала. Выбранный для взаимодействия gRPC — это открытый фреймворк Google, который позволяет вызывать удаленные процедуры (RPC) между клиентом и сервером, используя Protocol Buffers как язык описания интерфейса. gRPC имеет ряд преимуществ:

• высокая производительность благодаря использованию бинарного протокола HTTP/2;

• строгая типизация Protocol Buffers, которая отлично подходит для дизайна API и снижает вероятность ошибок при взаимодействии сервисов;

• .proto файлы с описанием структуры данных и API могут быть скомпилированы в код для различных языков программирования.

Для клиентской части, работающей в браузере, я использовал gRPC-web, поскольку браузеры не поддерживают обычный gRPC. gRPC-web позволяет взаимодействовать с обычными gRPC-сервисами из браузера. Пока что gRPC-web поддерживает только два режима взаимодействия: унарные вызовы и server-side стриминг.

Автоматизация

Мне показалось неудобным вручную создавать и подключать сгенерированные gRPC API пакеты. Поэтому я решил автоматизировать этот процесс через GitHub Actions и GitHub Packages. Дополнительно, чтобы гарантировать обратную совместимость изменений в API и следование официальному style guide от Google для .proto файлов, я внедрил проверки с помощью protolock и protolint.

О выборе GitHub Packages

Привлекательность использования GitHub Packages совместно с GitHub Actions, по моему мнению, заключается в следующем:

• простота настройки и деплоя пакетов в GitHub Packages в сравнении с Maven Central;

• централизация всех ресурсов проекта (код, CI/CD пайплайны, пакеты) на GitHub, что упрощает управление проектом;

• бесплатный тариф, включающий приватное хранение репозиториев и пакетов, а также их деплой.

Все эти преимущества делают GitHub Actions и Packages хорошим решением, особенно для Pet-проектов. Тем не менее есть и недостаток: в отличие от Maven Central, для скачивания опубликованных пакетов требуется GitHub-аккаунт и токен с правами на чтение пакетов. Как получить этот токен, я опишу ниже. 

Реализация

Для начала создадим Gradle-проект с использованием Kotlin DSL и добавим .proto файлы.

Proto-файл API проекта:

syntax = "proto3";

package com.arvgord.api.grpc.bankdemo.v1;

import "bankdemo/v1/messages/client_list_item.proto";
import "bankdemo/v1/messages/extracting_strategy.proto";
import "bankdemo/v1/messages/page_request.proto";
import "google/protobuf/wrappers.proto";

// Get client list request
message GetClientListRequest {
 // Current page
 PageRequest page_request = 1;
 // Extracting strategy
 ExtractingStrategy extracting_strategy = 2;
}

// Get client list response
message GetClientListResponse {
 // Clients
 repeated ClientListItem clients = 1;
 // Total number of clients
 google.protobuf.Int64Value total_clients = 2;
 // Total number of pages
 google.protobuf.Int32Value total_pages = 3;
}

// Service BankDemo
service BankDemo {
 // Get client list
 rpc GetClientList(GetClientListRequest) returns (GetClientListResponse);
}

Пример .proto файла сообщения PageRequest:

syntax = "proto3";

package com.arvgord.api.grpc.bankdemo.v1;

import "google/protobuf/wrappers.proto";

// Page
message PageRequest {
 // Number of clients on page
 google.protobuf.Int32Value page = 1;
 // Page size
 google.protobuf.Int32Value size = 2;
}

Настройка зависимостей проекта

Для управления версиями плагинов и библиотек проекта добавим в корень проекта файл gradle.properties с версиями зависимостей:

kotlinVersion=1.9.10
protobufPluginVersion=0.9.4
protobufKotlinVersion=3.24.4
grpcProtobufVersion=1.58.0
grpcKotlinVersion=1.4.0

Настроим файл settings.gradle.kts, в котором укажем название проекта:

rootProject.name = "bank-demo-api"

А также настроим менеджмент плагинов:

pluginManagement {
   val kotlinVersion: String by settings
   val protobufPluginVersion: String by settings
   plugins {
       kotlin("jvm") version kotlinVersion
       id("com.google.protobuf") version protobufPluginVersion
   }
   repositories {
       gradlePluginPortal()
   }
}

Версии плагинов, которые определены в settings.gradle.kts с помощью переменных, указанных в gradle.properties, автоматически используются в build.gradle.kts. Что избавляет от необходимости указывать их вручную.

Настроим файл build.gradle.kts. Добавим плагины:

plugins {
   kotlin("jvm")
   id("com.google.protobuf")
   id("maven-publish")
}

Эти плагины необходимы для компиляции проекта, .proto файлов и публикации пакетов в Apache Maven registry GitHub.

Добавим группу и версию библиотеки API, которые будут необходимы для публикации пакета:

group = "com.arvgord"
version = "0.0.1"

Название проекта name для публикации пакета будет взято из файла settings.gradle.kts. В итоге после публикации пакет будет выглядеть так: com.arvgord:bank-demo-api:0.0.1.

Укажем зависимости проекта, необходимые для добавления поддержки gRPC и Protocol Buffers для Kotlin:

dependencies {
   implementation("io.grpc:grpc-kotlin-stub:${property("grpcKotlinVersion")}")
   implementation("io.grpc:grpc-protobuf:${property("grpcProtobufVersion")}")
   implementation("com.google.protobuf:protobuf-kotlin:${property("protobufKotlinVersion")}")
}

Настройка protobuf плагина

Настроим плагин protobuf, чтобы генерировать код на основе .proto файлов:

protobuf {
   protoc {
       artifact = "com.google.protobuf:protoc:${property("protobufKotlinVersion")}"
   }
   plugins {
       id("grpc") {
           artifact = "io.grpc:protoc-gen-grpc-java:${property("grpcProtobufVersion")}"
       }
       id("grpckt") {
           artifact = "io.grpc:protoc-gen-grpc-kotlin:${property("grpcKotlinVersion")}:jdk8@jar"
       }
       id("protoc-gen-js") {
           path = projectDir.path.plus("/tools/protoc-gen-js-3.21.2-linux-x86_64")
       }
       id("protoc-gen-grpc-web") {
           path = projectDir.path.plus("/tools/protoc-gen-grpc-web-1.4.2-linux-x86_64")
       }
   }
   generateProtoTasks {
       all().forEach {
           it.plugins {
               id("grpc")
               id("grpckt")
               id("protoc-gen-js") {
                   option("import_style=commonjs,binary")
               }
               id("protoc-gen-grpc-web") {
                   option("import_style=commonjs+dts,mode=grpcweb")
               }
           }
           it.builtins {
               id("kotlin")
           }
       }
   }
}

Рассмотрим секцию plugins: 

• Плагины grpc и grpckt используются для генерации Java-кода, необходимого для сериализации/десериализации данных, а также создания серверного и клиентского gRPC кода на Kotlin. 

• Плагин protoc-gen-js необходим для генерации JavaScript кода на основе .proto файлов для сериализации/десериализации данных. Необходимо загрузить плагин и указать его расположение.

• Плагин protoc-gen-grpc-web позволяет генерировать код вызывающий gRPC-сервисы из веб-приложений. Этот плагин также необходимо загрузить и указать путь к расположению.

В секции generateProtoTasks определим задачи для генерации кода на основе .proto файлов. protoc-gen-grpc-web плагин позволяет генерировать как JS, так и TypeScript код. Так как мне необходимо было генерировать TypeScript код для вызова gRPC сервисов в options protoc-gen-js и protoc-gen-grpc-web, я использовал настройки import_style=commonjs,binary и import_style=commonjs+dts,mode=grpcweb. Вы можете использовать другие настройки.

Настройка публикации Maven-артефакта

Файл build.gradle.kts имеет следующие настройки:

publishing {
   repositories {
       maven {
           name = "GitHubPackages"
           url = uri("https://maven.pkg.github.com/arvgord/bank-demo-api")
           credentials {
               username = System.getenv("GITHUB_ACTOR")
               password = System.getenv("GITHUB_TOKEN")
           }
       }
   }
   publications {
       create<MavenPublication>("maven") {
           from(components["kotlin"])
       }
   }
}

В URL репозитория (https://maven.pkg.github.com/OWNER/REPOSITORY), куда планируется опубликовать пакет, необходимо заменить OWNER на имя вашего аккаунта на GitHub и REPOSITORY на имя вашего репозитория. В качестве username и password используются переменные среды GITHUB_ACTOR и GITHUB_TOKEN. Они будут автоматически подставлены при выполнении в GitHub Actions.

Настройка публикации npm-пакета

Для публикации npm-пакета я решил использовать отдельную директорию npm_package в корне проекта, содержащую только файл package.json с конфигурацией публикации. В build.gradle.kts необходимо добавить задачу для копирования сгенерированных TypeScript и JS файлов в директорию npm_package:

tasks.register<Copy>("buildAndCopy") {
   from(
       projectDir.path.plus("/build/generated/source/proto/main/protoc-gen-js"),
       projectDir.path.plus("/build/generated/source/proto/main/protoc-gen-grpc-web")
   )
   into(projectDir.path.plus("/npm_package/"))
}

Далее приступим к настройке файла package.json, содержащего конфигурацию для публикации npm-пакета:

{
 "name": "@arvgord/bank-demo-api",
 "version": "0.0.1",
 "description": "Generated typescript files for gRPC-web bank-demo-client application",
 "repository": {
   "type": "git",
   "url": "https://github.com/arvgord/bank-demo-api.git"
 },
 "dependencies": {
   "grpc-web": "^1.4.2",
   "google-protobuf": "^3.21.2"
 }
}

В этом файле:

• name определяет пространство имен и уникальное имя пакета;

• version указывает текущую версию пакета;

• description предоставляет краткое описание содержимого и предназначения пакета;

• repository указывает местоположение репозитория пакета;

• dependencies содержит список зависимостей, необходимых для работы пакета.

Настройка Action для публикации в GitHub Packages

Для файлов GitHub Actions необходимо в корне проекта создать директории .github/workflows.

Создадим файл конфигурации для публикации пакетов publish_packages.yml в директории .github/workflows:

name: Publish bank-demo-api packages
on:
  workflow_dispatch:

jobs:
 publish:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-java@v3
       with:
         java-version: '8'
         distribution: 'corretto'
     - name: Build packages
       run: ./gradlew buildAndCopy
     - name: Publish Kotlin gRPC API
       run: ./gradlew publish
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     - uses: actions/setup-node@v3
       with:
         node-version: '20.x'
         registry-url: 'https://npm.pkg.github.com'
         scope: '@arvgord'
     - name: Publish bank-demo-client gRPC API
       run: |
         cd ./npm_package
         npm i
         npm publish
       env:
         NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Разберем содержимое этого файла:

• workflow_dispatch: позволяет запускать workflow вручную из интерфейса GitHub в разделе Actions.

• actions/checkout@v4: клонирование кода репозитория.

• setup-java@v3: установка Java 8 версии.

• ./gradlew buildAndCopy: сборка пакетов.

• ./gradlew publish: с помощью команды происходит публикация Kotlin пакета в GitHub Apache Maven registry. Для аутентификации используется GITHUB_TOKEN. GITHUB_ACTOR подставляется в build.gradle.kts автоматически т.к. является стандартной переменной окружения.

• actions/setup-node@v3: настройка окружения Node.js версии 20.x для последующей публикации npm пакета.

• Publish bank-demo-client gRPC API: происходит переход в директорию npm_package, установка зависимостей и публикация npm-пакета с использованием NODE_AUTH_TOKEN.

При последующих запусках сборки и публикации пакетов необходимо поднять версии публикуемых пакетов, чтобы избежать ошибок конфликта их версий:

1. В файле build.gradle.kts необходимо обновить значение version.

2. В файле package.json также обновить значение version.

Настройка прокси

В самом начале я упоминал о ключевой особенности: gRPC-web клиенты не способны напрямую связываться с обычными gRPC-сервисами. Чтобы обеспечить взаимодействие, требуется проксирование. В проекте я применяю envoy прокси. Настройки были реализованы на основе примера, доступного в репозитории gRPC-web и выглядят следующим образом:

admin:
 access_log_path: /tmp/admin_access.log
 address:
   socket_address: { address: 0.0.0.0, port_value: 9901 }


static_resources:
 listeners:
   - name: listener_0
     address:
       socket_address: { address: 0.0.0.0, port_value: 8080 }
     filter_chains:
       - filters:
           - name: envoy.filters.network.http_connection_manager
             typed_config:
               "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
               codec_type: auto
               stat_prefix: ingress_http
               route_config:
                 name: local_route
                 virtual_hosts:
                   - name: local_service
                     domains: ["*"]
                     routes:
                       - match: { prefix: "/" }
                         route:
                           cluster: echo_service
                           timeout: 0s
                           max_stream_duration:
                             grpc_timeout_header_max: 0s
                     cors:
                       allow_origin_string_match:
                         - prefix: "*"
                       allow_methods: GET, PUT, DELETE, POST
                       allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,custom-header-1,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web,grpc-timeout
                       max_age: "1728000"
                       expose_headers: custom-header-1,grpc-status,grpc-message
               http_filters:
                 - name: envoy.filters.http.grpc_web
                   typed_config:
                     "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
                 - name: envoy.filters.http.cors
                   typed_config:
                     "@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors
                 - name: envoy.filters.http.router
                   typed_config:
                     "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
 clusters:
   - name: echo_service
     connect_timeout: 0.25s
     type: logical_dns
     http2_protocol_options: {}
     lb_policy: round_robin
     load_assignment:
       cluster_name: cluster_0
       endpoints:
         - lb_endpoints:
             - endpoint:
                 address:
                   socket_address:
                     address: 172.17.0.1
                     port_value: 6565

Подключение API

Как я описывал в начале, для возможности скачивания пакетов из GitGub Packages необходимо создать токен согласно инструкции, с правами на чтение пакетов.

Настроим подключение к GitHub Apache maven registry на бэкенде для проекта, который будет использовать опубликованный пакет:

repositories {
   mavenCentral()
   maven {
       url = uri("https://maven.pkg.github.com/arvgord/bank-demo-api")
       credentials {
           username = project.findProperty("gpr.user") as String? ?:
("GITHUB_ACTOR")
           password = project.findProperty("gpr.key") as String? ?:
("GITHUB_TOKEN")
       }
   }
}

В URL https://maven.pkg.github.com/OWNER/REPOSITORY необходимо заменить OWNER на имя аккаунта на GitHub и REPOSITORY на имя репозитория, откуда планируете скачивать пакет. В системных переменных необходимо задать токен на чтение GITHUB_TOKEN.

Вот как происходит вызов gRPC API на бэкенде подключенного пакета:

package com.arvgord.bankdemoserver.controller.grpc.cartesianissue.v1

import com.arvgord.api.grpc.bankdemo.v1.BankDemoGrpcKt
import com.arvgord.api.grpc.bankdemo.v1.BankDemoOuterClass.GetClientListRequest
import com.arvgord.api.grpc.bankdemo.v1.BankDemoOuterClass.GetClientListResponse
import io.grpc.Status
import io.grpc.StatusException
import org.lognet.springboot.grpc.GRpcService
import com.arvgord.bankdemoserver.controller.grpc.cartesianissue.v1.adapter.BankDemoAdapter

@GRpcService
class BankDemoCartesianIssueController(
   private val adapter: BankDemoAdapter
) : BankDemoGrpcKt.BankDemoCoroutineImplBase() {
  
   override suspend fun getClientList(request: GetClientListRequest): GetClientListResponse =
       try {
           adapter.getClientList(request)
       } catch (e: Exception) {
           throw StatusException(Status.INTERNAL.withDescription(e.message))
       }
}

Для подключения к npm GitHub registry необходимо:

1. Выполнить команду npm login --registry=https://npm.pkg.github.com.

2. Ввести имя аккаунта на GitHub и GITHUB_TOKEN на чтение пакетов.

3. Выполнить npm i в вашем проекте.

Так выглядит вызов gRPC API на React-клиенте:

import {useEffect, useState} from 'react';
import {GetClientListRequest, GetClientListResponse} from "@arvgord/bank-demo-api/bankdemo/v1/api/business/bank_demo_pb";
import {PageRequest} from "@arvgord/bank-demo-api/bankdemo/v1/messages/page_request_pb";
import {Int32Value} from "google-protobuf/google/protobuf/wrappers_pb";
import {ExtractingStrategy} from "@arvgord/bank-demo-api/bankdemo/v1/messages/extracting_strategy_pb";
import {BankDemoPromiseClient} from "@arvgord/bank-demo-api/bankdemo/v1/api/business/bank_demo_grpc_web_pb";

export function useGetList(page: number, size: number, strategy: ExtractingStrategy) {
   const [response, setResponse] = useState(new GetClientListResponse().toObject())
   const [error, setError] = useState()

   useEffect(() => {
       if (!page && !size && !strategy) return
       const service = new BankDemoPromiseClient('http://localhost:8080', null, null)
       const request = new GetClientListRequest()
       const pageRequest = new PageRequest()
       pageRequest.setPage(new Int32Value().setValue(page))
       pageRequest.setSize(new Int32Value().setValue(size))
       request.setPageRequest(pageRequest)
       request.setExtractingStrategy(strategy)
       service.getClientList(request, {})
           .then(result => result.toObject())
           .then(setResponse)
           .catch(setError)
   }, [page, size, strategy]);

   return {
       response,
       error
   };
}

Основная реализация готова. Так как материал получился достаточно обширным, подключение проверок protolock protolint я рассмотрю в отдельных публикациях.

Исходный код описанных примеров вы найдете в проекте на GitHub, как и пример подключения API к клиенту и бэкенду.

Заключение

gRPC — это мощный фреймворк для создания эффективных и надежных API. На основе .proto файлов вы можете одновременно генерировать как серверный код, так и код для веб-клиентов. Генерация и публикация gRPC API пакетов значительно упрощается с использованием GitHub Actions и GitHub Packages, что и было продемонстрировано в этом посте.