Go SDK [community]

Сообщественный SDK

Данный SDK полностью поддерживается сообществом.

Remnawave Go SDK — это библиотека для удобного взаимодействия с RestAPI.

✨ Ключевые возможности

Сгенерирован с помощью ogen v1.19.0: JSON-декодер без рефлексии для высокой пропускной способности
Типобезопасность: Проверка на этапе компиляции по спецификации OpenAPI 3.0
Дизайн на основе контроллеров: Организованные под-клиенты для чистого доступа к API
Упрощённые сигнатуры: Без громоздких структур Params для простых операций
Поддержка контекста: Поддержка context.Context первого класса
OpenTelemetry: Встроенная инструментация трассировки
Опции запросов: Настройка на уровне запроса через ...RequestOption
Редакторы: Поддержка middleware запросов/ответов

Установка

go get github.com/Jolymmiles/remnawave-api-go/v2@latest

warning

Всегда выбирайте и фиксируйте правильную версию SDK, соответствующую версии бэкенда Remnawave.

Версия SDK	Версия панели Remnawave
v2.6.1	2.6.1
v2.5.3	2.5.3
v2.3.0-6	2.3.0
v2.2.6-3	2.2.6

Использование

Базовый пример

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    // Create base client
    baseClient, err := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    if err != nil {
        log.Fatal(err)
    }

    // Wrap with organized sub-clients
    client := remapi.NewClientExt(baseClient)

    // Get user by UUID - simplified signature
    resp, err := client.Users().GetUserByUuid(ctx, "user-uuid-here")
    if err != nil {
        log.Fatal(err)
    }

    switch r := resp.(type) {
    case *remapi.UserResponse:
        fmt.Printf("User: %s\n", r.Response.Username)
    case *remapi.NotFoundError:
        fmt.Println("User not found")
    case *remapi.BadRequestError:
        fmt.Printf("Validation error: %v\n", r.Errors)
    }
}

Создание пользователей и управление ими

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Create user
    createResp, err := client.Users().CreateUser(ctx, &remapi.CreateUserRequest{
        Username: "john_doe",
    })
    if err != nil {
        log.Fatal(err)
    }

    user := createResp.(*remapi.UserResponse).Response
    fmt.Printf("Created user: %s (UUID: %s)\n", user.Username, user.UUID)

    // Disable user
    _, err = client.Users().DisableUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User disabled")

    // Enable user
    _, err = client.Users().EnableUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User enabled")

    // Delete user
    _, err = client.Users().DeleteUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User deleted")
}

Управление узлами

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Get all nodes
    nodesResp, err := client.Nodes().GetAllNodes(ctx)
    if err != nil {
        log.Fatal(err)
    }

    nodes := nodesResp.(*remapi.NodesResponse).Response
    fmt.Printf("Total nodes: %d\n", len(nodes))

    for _, node := range nodes {
        fmt.Printf("  - %s (%s): connected=%v\n",
            node.Name, node.Address, node.IsConnected)
    }

    // Get single node
    if len(nodes) > 0 {
        nodeResp, _ := client.Nodes().GetOneNode(ctx, nodes[0].UUID.String())
        node := nodeResp.(*remapi.NodeResponse).Response
        fmt.Printf("\nNode details: %s\n", node.Name)
    }
}

Пагинация

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Use PaginationHelper for iterating through pages
    pager := remapi.NewPaginationHelper(50) // 50 items per page

    for pager.HasMore {
        resp, err := client.Users().GetAllUsers(ctx,
            pager.Limit,  // size
            pager.Offset, // start
        )
        if err != nil {
            log.Fatal(err)
        }

        users := resp.(*remapi.GetAllUsersResponse)
        for _, user := range users.Response.Users {
            fmt.Printf("User: %s (UUID: %s)\n", user.Username, user.UUID)
        }

        // Advance to next page
        pager.SetTotal(int(users.Response.Total))
        pager.NextPage()
    }

    fmt.Printf("Total users: %d\n", *pager.Total)
}

Обработка ошибок

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    resp, err := client.Users().GetUserByUuid(ctx, "invalid-uuid")
    if err != nil {
        log.Fatal("Network error:", err)
    }

    // Available error types depend on the endpoint — check the generated
    // Res interface (e.g. UsersGetUserByUuidRes) for the full list.
    switch e := resp.(type) {
    case *remapi.UserResponse:
        fmt.Printf("User found: %s\n", e.Response.Username)
    case *remapi.BadRequestError:
        fmt.Println("Validation errors:")
        for _, ve := range e.Errors {
            fmt.Printf("  - %s: %s (path: %v)\n",
                ve.Code, ve.Message, ve.Path)
        }
    case *remapi.NotFoundError:
        fmt.Println("Resource not found")
    case *remapi.InternalServerError:
        fmt.Printf("Server error: %s\n", e.Message.Value)
    }
}

Доступные контроллеры

Контроллер	Описание
`client.ApiTokens()`	Управление API-токенами
`client.Auth()`	Аутентификация
`client.BandwidthStatsNodes()`	Статистика пропускной способности узлов
`client.BandwidthStatsUsers()`	Статистика пропускной способности пользователей
`client.ConfigProfile()`	Профили конфигурации
`client.ExternalSquad()`	Внешние группы
`client.Hosts()`	Управление хостами
`client.HostsBulkActions()`	Массовые операции с хостами
`client.HwidUserDevices()`	HWID-устройства
`client.InfraBilling()`	Биллинг инфраструктуры
`client.InternalSquad()`	Внутренние группы
`client.Keygen()`	Генерация ключей
`client.Nodes()`	Управление узлами
`client.NodesUsageHistory()`	История использования узлов
`client.Passkey()`	Аутентификация по ключу
`client.RemnawaveSettings()`	Настройки панели
`client.Snippets()`	Фрагменты кода
`client.Subscription()`	Управление подпиской
`client.SubscriptionPageConfig()`	Настройка страницы подписки
`client.SubscriptionSettings()`	Настройки подписки
`client.SubscriptionTemplate()`	Шаблоны подписки
`client.Subscriptions()`	Несколько подписок
`client.System()`	Системная информация
`client.UserSubscriptionRequestHistory()`	История запросов
`client.Users()`	Управление пользователями
`client.UsersBulkActions()`	Массовые операции с пользователями

Типы ошибок

Тип	HTTP-статус	Описание
`BadRequestError`	400	Ошибки валидации с подробностями
`UnauthorizedError`	401	Требуется аутентификация
`ForbiddenError`	403	Доступ запрещён
`NotFoundError`	404	Ресурс не найден
`InternalServerError`	500	Ошибка сервера

🛠️ Ссылки на проект

Репозиторий GitHub: remnawave-api-go на GitHub
Автор: Jolymmiles

Установка​

Использование​

Доступные контроллеры​

Типы ошибок​

🛠️ Ссылки на проект​

Установка

Использование

Доступные контроллеры

Типы ошибок

🛠️ Ссылки на проект