Go SDK [community]
コミュニティ SDK
このSDKは完全にコミュニティによってメンテナンスされています。
Remnawave Go SDKは、RestAPIとの便利なやり取りのためのライブラリです。
✨ 主な機能
- ogen v1.19.0 で生成: 高スループットのためのゼロリフレクション JSON デコーダー
- 型安全: OpenAPI 3.0 仕様に対するコンパイル時検証
- コントローラーベース設計: クリーンな API アクセスのための整理されたサブクライアント
- 簡素化されたシグネチャ: 単純な操作のための冗長な Params 構造体が不要
- コンテキストサポート: ファーストクラスの
context.Contextサポート - OpenTelemetry: 組み込みのトレース計装
- リクエストオプション:
...RequestOptionによるリクエストごとのカスタマイズ - エディター: リクエスト/レスポンスミドルウェアサポート
インストール
go get github.com/Jolymmiles/remnawave-api-go/v2@latest
警告
常にRemnawaveバックエンドのバージョンに合った正しいバージョンのSDKを選択し、固定してください。
| 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 on GitHub
- 作者: Jolymmiles