راهنمای gRPC

APIهای پرکارایی gRPC برای شبکه‌سازی مش، اتصال VPN و اطلاعات تهدید. Protocol Buffers، جریان‌سازی دوطرفه و تأخیر زیر یک میلی‌ثانیه.

gRPC + Protocol Buffers

APIهای پرکارایی gRPC

سرویس‌های RPC مبتنی بر Protocol Buffer برای شبکه‌سازی مش، مدیریت تونل VPN و اطلاعات تهدید. جریان‌سازی دوطرفه، نوع‌دهی قوی و سربار زیر یک میلی‌ثانیه.

0
کل RPCها
0
سرویس gRPC
0
الگوی جریان‌سازی
0
Protocol Buffers

مرور کلی

APIهای gRPC سرویس OrbVPN برای ارتباط کم‌تأخیر و پرگذردهی میان سرویس‌ها طراحی شده‌اند. این‌ها پروتکل اصلی برای شبکه‌سازی مش (OrbMesh)، مدیریت تونل VPN و جریان‌سازی بی‌درنگ اطلاعات تهدید هستند.

Protocol Buffers

پیام‌های نوع‌دهی‌شدهٔ قوی و باینری‌سریالایز که ۵ تا ۱۰ برابر کوچک‌تر از JSON و به‌طور چشمگیری برای تجزیه سریع‌ترند. نحو Proto3 با سازگاری کامل رو به عقب.

جریان‌سازی دوطرفه

پشتیبانی کامل از هر چهار الگوی gRPC: یک‌طرفه (unary)، جریان‌سازی سمت سرور، جریان‌سازی سمت کلاینت و جریان‌سازی دوطرفه. عالی برای سنجه‌های بی‌درنگ و فیدهای تهدید.

انتقال HTTP/2

ساخته‌شده بر پایهٔ HTTP/2 با جریان‌های چندگانه (multiplexed)، فشرده‌سازی سرآیند و کنترل جریان. چندین RPC یک اتصال TCP واحد را به اشتراک می‌گذارند.

تولید کد

از روی فایل‌های proto به‌طور مستقیم، استاب‌های کلاینت نوع‌ایمن را در Go، Python، JavaScript، Java، C++ و بیش از ۱۰ زبان دیگر تولید کنید.


برپاسازی اتصال

سه نقطه پایانی gRPC بخش‌های مختلف پلتفرم OrbVPN را سرویس‌دهی می‌کنند.

سرویسآدرسTLSاحراز هویت
OrbNET gRPCgrpc://api.orbai.world:50051TLS 1.3فراداده JWT
OrbMesh gRPCبرای هر سرور IP:50051mTLSگواهی کلاینت
OrbGuard gRPCgrpc://guard.orbai.world:50051TLS 1.3فراداده کلید API

احراز هویت

هر سرویس gRPC از یک سازوکار احراز هویت متفاوت استفاده می‌کند که به‌صورت فرادادهٔ gRPC (معادل سرآیندهای HTTP) ارسال می‌شود.

OrbNET — فراداده JWT

توکن دسترسی JWT خود را به‌عنوان کلید فرادادهٔ authorization پیوست کنید.

import "google.golang.org/grpc/metadata"

md := metadata.Pairs("authorization", "Bearer eyJhbGciOiJIUzI1NiIs...")
ctx := metadata.NewOutgoingContext(context.Background(), md)

resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "usr_abc123"})

OrbGuard — فراداده کلید API

کلید API خود را به‌عنوان کلید فرادادهٔ x-api-key پیوست کنید.

md := metadata.Pairs("x-api-key", "ogk_live_abc123...")
ctx := metadata.NewOutgoingContext(context.Background(), md)

resp, err := threatClient.CheckIndicator(ctx, &pb.CheckIndicatorRequest{
    Indicator: "suspicious-domain.com",
    Type:      pb.IndicatorType_DOMAIN,
})

OrbMesh — mTLS (احراز هویت متقابل TLS)

گره‌های OrbMesh با استفاده از گواهی‌های کلاینت صادرشده توسط CA سرویس OrbVPN احراز هویت می‌شوند.

import "google.golang.org/grpc/credentials"

creds, err := credentials.NewClientTLSFromFile("ca.pem", "")
// For mTLS, load both client cert and key
tlsCert, err := tls.LoadX509KeyPair("client.pem", "client-key.pem")

tlsConfig := &tls.Config{
    Certificates: []tls.Certificate{tlsCert},
    RootCAs:      certPool,
}

conn, err := grpc.Dial(
    "mesh-node-ip:50051",
    grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
)

تأمین گواهی

گواهی‌های گرهِ OrbMesh به‌طور خودکار در جریان ثبت گره تأمین می‌شوند. برای مشاهدهٔ فرایند کامل راه‌اندازی، به مرور کلی OrbMesh مراجعه کنید.


سرویس‌ها

۱. OrbMeshService

صفحهٔ کنترل شبکه‌سازی مش. ثبت گره، پایش سلامت، توپولوژی و جمع‌آوری بی‌درنگ سنجه‌ها را در سراسر ناوگان سرورهای OrbVPN مدیریت می‌کند.

gRPC

OrbMeshService

صفحهٔ کنترل شبکه‌سازی مش برای مدیریت ناوگان سرورهای OrbVPN، پایش سلامت و کنترل توپولوژی.

RegisterNode
Unary
Heartbeat
Unary
StreamMetrics
استریم سرور
PushMetrics
استریم کلاینت
SyncTopology
دوطرفه
GetNodeStatus
Unary
ListNodes
Unary
DrainNode
Unary
RotateCertificates
Unary
DeregisterNode
Unary

۲. VPNService

مدیریت چرخهٔ عمر تونل VPN. از پروتکل‌های WireGuard، VLESS و OrbConnect همراه با جریان‌سازی بی‌درنگ وضعیت پشتیبانی می‌کند.

gRPC

VPNService

مدیریت چرخهٔ عمر تونل VPN برای پروتکل‌های WireGuard، VLESS و OrbConnect.

ConnectWireGuard
Unary
ConnectVLESS
Unary
ConnectOrbConnect
Unary
Disconnect
Unary
GetStatus
Unary
StreamStatus
استریم سرور

۳. ThreatIntelligenceService

شناسایی بی‌درنگ تهدید، بررسی نشانگرها و تحلیل انبوه تهدید از OrbGuard Labs.

gRPC

ThreatIntelligenceService

اطلاعات تهدید و تحلیل نشانگر از OrbGuard Labs. نشانگرها را بررسی کنید، تهدیدهای زنده را جریان‌سازی کنید و تحلیل انبوه انجام دهید.

CheckIndicator
Unary
StreamThreats
استریم سرور
BatchCheck
Unary
StreamIndicators
استریم کلاینت
LiveAnalysis
دوطرفه

انواع پیام کلیدی

RegisterNodeRequest

messageRegisterNodeRequest
#فیلدنوعتوضیحات
1
hostnamereq
stringنام میزبان کاملاً مقیدِ گره.
2
ip_addressreq
stringنشانی IP عمومی گره.
3
regionreq
stringکد منطقهٔ جغرافیایی (مثلاً us-east-1، eu-west-1).
4
repeatedprotocols
Protocolفهرست پروتکل‌های VPN پشتیبانی‌شده (WIREGUARD، VLESS، ORBCONNECT).
5
capacityreq
NodeCapacityبیشینهٔ ظرفیت اتصال و محدودیت‌های منابع برای گره.
6
labels
map<string, string>برچسب‌های کلید-مقدار دلخواه برای دسته‌بندی گره و قواعد مسیریابی.

ConnectWireGuardRequest

messageConnectWireGuardRequest
#فیلدنوعتوضیحات
1
user_idreq
stringشناسهٔ کاربرِ احراز هویت‌شده.
2
device_idreq
stringشناسهٔ یکتای دستگاه برای کلاینت در حال اتصال.
3
server_id
stringشناسهٔ سرور ترجیحی. اگر خالی باشد، صفحهٔ کنترل بهینه‌ترین سرور را انتخاب می‌کند.
4
public_keyreq
bytesکلید عمومی WireGuard دستگاه کلاینت (۳۲ بایت، Curve25519).
5
preshared_key
bytesکلید ازپیش‌به‌اشتراک‌گذاشتهٔ اختیاری WireGuard برای مقاومت پساکوانتومی (۳۲ بایت).
6
preferred_endpoint
stringمنطقهٔ سرور یا کد شهر ترجیحی برای بهینه‌سازی جغرافیایی.
7
kill_switch
boolفعال‌سازی قواعد kill switch در پاسخ سرور (مسدودکردن ترافیک در صورت افتادن تونل).

CheckIndicatorRequest

messageCheckIndicatorRequest
#فیلدنوعتوضیحات
1
indicatorreq
stringمقدار نشانگری که باید بررسی شود (دامنه، نشانی IP، URL یا هشِ فایل).
2
typereq
IndicatorTypeنوع نشانگر: DOMAIN، IP، URL، SHA256، MD5 یا SHA1.
3
include_context
boolگنجاندن زمینهٔ غنی‌سازی (WHOIS، تاریخچهٔ DNS، نشانگرهای مرتبط) در پاسخ.
4
include_yara_matches
boolاجرای قواعد منطبق YARA و گنجاندن نتایج (فقط برای نشانگرهای هشِ فایل کاربرد دارد).

ThreatEvent

messageThreatEvent
#فیلدنوعتوضیحات
1
idreq
stringشناسهٔ یکتای رویداد.
2
indicatorreq
stringنشانگر تهدید (دامنه، IP، URL یا هش).
3
indicator_typereq
IndicatorTypeنوع نشانگر.
4
severityreq
Severityشدت تهدید: INFO، LOW، MEDIUM، HIGH یا CRITICAL.
5
scorereq
int32امتیاز تهدید از ۰ (بی‌خطر) تا ۱۰۰ (بدافزارِ تأییدشده).
6
repeatedcategories
stringدسته‌های تهدید: malware، phishing، c2، spam، cryptominer و غیره.
7
first_seenreq
google.protobuf.Timestampزمانی که نشانگر برای نخستین‌بار توسط OrbGuard مشاهده شد.
8
last_seenreq
google.protobuf.Timestampزمانی که نشانگر برای آخرین‌بار مشاهده شد.

نمونه‌های کد

Go — RPC یک‌طرفه

package main

import (
    "context"
    "fmt"
    "log"

    pb "github.com/orbvpn/proto/orbguard/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    // Connect with TLS
    creds, err := credentials.NewClientTLSFromFile("ca.pem", "guard.orbai.world")
    if err != nil {
        log.Fatal(err)
    }

    conn, err := grpc.Dial("guard.orbai.world:50051", grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    client := pb.NewThreatIntelligenceServiceClient(conn)

    // Attach API key
    ctx := metadata.AppendToOutgoingContext(
        context.Background(),
        "x-api-key", "ogk_live_abc123...",
    )

    // Check a threat indicator
    resp, err := client.CheckIndicator(ctx, &pb.CheckIndicatorRequest{
        Indicator:      "suspicious-domain.com",
        Type:           pb.IndicatorType_DOMAIN,
        IncludeContext: true,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Indicator: %s\n", resp.Indicator)
    fmt.Printf("Score:     %d/100\n", resp.Score)
    fmt.Printf("Severity:  %s\n", resp.Severity)
    fmt.Printf("Malicious: %v\n", resp.IsMalicious)

    for _, cat := range resp.Categories {
        fmt.Printf("  Category: %s\n", cat)
    }
}

Go — جریان‌سازی سمت سرور

// Stream real-time threat events
stream, err := client.StreamThreats(ctx, &pb.StreamThreatsRequest{
    Severity:   []pb.Severity{pb.Severity_HIGH, pb.Severity_CRITICAL},
    Categories: []string{"malware", "phishing", "c2"},
})
if err != nil {
    log.Fatal(err)
}

for {
    event, err := stream.Recv()
    if err != nil {
        log.Println("Stream ended:", err)
        break
    }

    fmt.Printf("[%s] %s -- %s (score: %d)\n",
        event.Severity,
        event.IndicatorType,
        event.Indicator,
        event.Score,
    )
}

Go — جریان‌سازی دوطرفه

// Bidirectional topology sync with OrbMesh
stream, err := meshClient.SyncTopology(ctx)
if err != nil {
    log.Fatal(err)
}

// Send local topology updates in a goroutine
go func() {
    updates := getLocalTopologyUpdates() // your implementation
    for _, update := range updates {
        if err := stream.Send(&update); err != nil {
            log.Println("Send error:", err)
            return
        }
    }
    stream.CloseSend()
}()

// Receive cluster-wide topology updates
for {
    update, err := stream.Recv()
    if err != nil {
        log.Println("Stream ended:", err)
        break
    }

    fmt.Printf("Topology update: node=%s action=%s\n",
        update.NodeId, update.Action)
    applyTopologyUpdate(update) // your implementation
}

Python — RPC یک‌طرفه

import grpc
from orbguard.v1 import threat_service_pb2 as pb
from orbguard.v1 import threat_service_pb2_grpc as pb_grpc

# Connect with TLS
credentials = grpc.ssl_channel_credentials(
    root_certificates=open("ca.pem", "rb").read()
)

channel = grpc.secure_channel("guard.orbai.world:50051", credentials)
client = pb_grpc.ThreatIntelligenceServiceStub(channel)

# Attach API key metadata
metadata = [("x-api-key", "ogk_live_abc123...")]

# Check a threat indicator
response = client.CheckIndicator(
    pb.CheckIndicatorRequest(
        indicator="suspicious-domain.com",
        type=pb.DOMAIN,
        include_context=True,
    ),
    metadata=metadata,
)

print(f"Indicator: {response.indicator}")
print(f"Score:     {response.score}/100")
print(f"Severity:  {pb.Severity.Name(response.severity)}")
print(f"Malicious: {response.is_malicious}")

Python — جریان‌سازی سمت سرور

# Stream real-time threats
stream = client.StreamThreats(
    pb.StreamThreatsRequest(
        severity=[pb.HIGH, pb.CRITICAL],
        categories=["malware", "phishing"],
    ),
    metadata=metadata,
)

for event in stream:
    print(f"[{pb.Severity.Name(event.severity)}] "
          f"{pb.IndicatorType.Name(event.indicator_type)}: "
          f"{event.indicator} (score: {event.score})")

Python — جریان‌سازی دوطرفهٔ ناهمگام

import asyncio
import grpc.aio

async def live_analysis():
    channel = grpc.aio.secure_channel(
        "guard.orbai.world:50051",
        grpc.ssl_channel_credentials(open("ca.pem", "rb").read()),
    )
    client = pb_grpc.ThreatIntelligenceServiceStub(channel)
    metadata = [("x-api-key", "ogk_live_abc123...")]

    # Bidirectional stream
    async def indicator_generator():
        indicators = [
            ("suspicious-domain.com", pb.DOMAIN),
            ("192.168.1.100", pb.IP),
            ("https://phishing-site.com/login", pb.URL),
        ]
        for indicator, itype in indicators:
            yield pb.AnalysisRequest(indicator=indicator, type=itype)
            await asyncio.sleep(0.1)  # Simulate real-time submissions

    stream = client.LiveAnalysis(indicator_generator(), metadata=metadata)

    async for result in stream:
        print(f"Result: {result.indicator} -> score={result.score}, "
              f"malicious={result.is_malicious}")

asyncio.run(live_analysis())

الگوهای جریان‌سازی

gRPC از چهار الگوی ارتباطی پشتیبانی می‌کند. سرویس OrbVPN از هر چهار الگو در سرویس‌های خود استفاده می‌کند.

یک‌طرفه (Unary)

درخواست-پاسخ کلاسیک. کلاینت یک درخواست می‌فرستد و سرور یک پاسخ بازمی‌گرداند. برای CheckIndicator، RegisterNode و ConnectWireGuard استفاده می‌شود.

جریان‌سازی سمت سرور

کلاینت یک درخواست می‌فرستد و سرور یک جریان از پاسخ‌ها بازمی‌گرداند. برای StreamMetrics، StreamThreats و StreamStatus استفاده می‌شود.

جریان‌سازی سمت کلاینت

کلاینت یک جریان از درخواست‌ها می‌فرستد و سرور یک پاسخ بازمی‌گرداند. برای PushMetrics و StreamIndicators استفاده می‌شود.

جریان‌سازی دوطرفه

هم کلاینت و هم سرور به‌طور مستقل جریان‌هایی از پیام‌ها می‌فرستند. برای SyncTopology و LiveAnalysis استفاده می‌شود.

مقایسهٔ الگوها

الگوکاربردنمونه‌های OrbVPN
Unaryیک درخواست، یک پاسخCheckIndicator، RegisterNode، ConnectWireGuard
Server Streamاشتراک در دادهٔ پیوستهStreamMetrics، StreamThreats، StreamStatus
Client Streamارسال دادهٔ دسته‌ایPushMetrics، StreamIndicators
Bidirectionalهمگام‌سازی بی‌درنگ، تحلیل تعاملیSyncTopology، LiveAnalysis

مرجع فایل‌های Proto

فایل‌های proto را دانلود کنید تا استاب‌های کلاینت را در هر زبان پشتیبانی‌شده تولید کنید.

فایل Protoبستهتوضیح
orbmesh/v1/mesh_service.protoorbvpn.mesh.v1صفحهٔ کنترل OrbMesh — مدیریت گره، توپولوژی، سنجه‌ها
orbnet/v1/vpn_service.protoorbvpn.vpn.v1مدیریت تونل VPN — WireGuard، VLESS، OrbConnect
orbguard/v1/threat_service.protoorbvpn.guard.v1اطلاعات تهدید — نشانگرها، تحلیل، جریان‌سازی
orbvpn/v1/common.protoorbvpn.v1انواع مشترک — Severity، IndicatorType، Protocol، NodeCapacity

دسترسی به فایل‌های Proto

فایل‌های proto در مخزن GitHub سرویس OrbVPN در دسترس‌اند. مخزن را کلون کنید و با protoc یا buf کد کلاینت را به زبان خودتان تولید کنید.

تولید کد کلاینت

# Using protoc (Go example)
protoc --go_out=. --go-grpc_out=. \
  -I proto/ \
  proto/orbguard/v1/threat_service.proto

# Using buf (recommended)
buf generate proto/

# Using grpc_tools (Python)
python -m grpc_tools.protoc \
  -I proto/ \
  --python_out=. \
  --grpc_python_out=. \
  proto/orbguard/v1/threat_service.proto

ابزارهای توسعه

grpcurl

ابزار خط فرمان برای تعامل با سرورهای gRPC. مانند cURL اما برای gRPC. از reflection، ورودی JSON و جریان‌سازی پشتیبانی می‌کند.

Evans

کلاینت جامع و گویای gRPC با رابط REPL. برای کاوش تعاملی سرویس‌ها همراه با تکمیل خودکار با Tab عالی است.

BloomRPC

کلاینت گرافیکی برای سرویس‌های gRPC. فایل‌های proto را وارد کنید، درخواست بفرستید و پاسخ‌ها را با رابطی شبیه Postman بررسی کنید.

نمونه‌های grpcurl

# List available services (requires server reflection)
grpcurl -cacert ca.pem guard.orbai.world:50051 list

# Describe a service
grpcurl -cacert ca.pem guard.orbai.world:50051 \
  describe orbvpn.guard.v1.ThreatIntelligenceService

# Check a threat indicator
grpcurl -cacert ca.pem \
  -H "x-api-key: ogk_live_abc123..." \
  -d '{"indicator": "suspicious-domain.com", "type": "DOMAIN"}' \
  guard.orbai.world:50051 \
  orbvpn.guard.v1.ThreatIntelligenceService/CheckIndicator

# Stream threats (server streaming)
grpcurl -cacert ca.pem \
  -H "x-api-key: ogk_live_abc123..." \
  -d '{"severity": ["HIGH", "CRITICAL"]}' \
  guard.orbai.world:50051 \
  orbvpn.guard.v1.ThreatIntelligenceService/StreamThreats

مدیریت خطا

gRPC از کدهای وضعیت استاندارد استفاده می‌کند. سرویس‌های OrbVPN جزئیات خطای بیشتری را در فرادادهٔ وضعیت بازمی‌گردانند.

کد gRPCمعناعلت رایج
OK (0)موفقیت
INVALID_ARGUMENT (3)درخواست نامعتبرفیلد مفقود یا نامعتبر در پیام درخواست
NOT_FOUND (5)منبع یافت نشدگره، کاربر یا نشانگر یافت نشد
PERMISSION_DENIED (7)شکست احراز هویتJWT/کلید API نامعتبر یا منقضی‌شده
RESOURCE_EXHAUSTED (8)محدودشده با نرخدرخواست‌های بیش از حد — با عقب‌نشینی دوباره تلاش کنید
UNAVAILABLE (14)سرویس از دسترس خارجخطای گذرا — با عقب‌نشینی دوباره تلاش کنید
UNAUTHENTICATED (16)بدون اعتبارنامهفرادادهٔ authorization مفقود
import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

resp, err := client.CheckIndicator(ctx, req)
if err != nil {
    st, ok := status.FromError(err)
    if ok {
        switch st.Code() {
        case codes.Unauthenticated:
            // Refresh token and retry
        case codes.ResourceExhausted:
            // Rate limited -- backoff and retry
        case codes.Unavailable:
            // Transient failure -- retry with backoff
        default:
            log.Fatalf("gRPC error: %s -- %s", st.Code(), st.Message())
        }
    }
}

مهلت / وقفهٔ زمانی

همیشه برای زمینهٔ gRPC خود یک مهلت تعیین کنید. بدون مهلت، یک RPC گیرکرده می‌تواند منابع را به‌طور نامحدود اشغال کند. مهلت ۳۰ ثانیه‌ای یک پیش‌فرض خوب برای RPCهای یک‌طرفه است. برای RPCهای جریان‌سازی، از مهلت طولانی‌تری استفاده کنید یا وقفه‌های زمانی در سطح برنامه پیاده‌سازی کنید.

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

resp, err := client.CheckIndicator(ctx, req)

نکات کارایی

اتصال‌ها را دوباره استفاده کنید

اتصال‌های gRPC روی یک اتصال TCP واحد چندگانه (multiplex) می‌شوند. برای هر مقصد یک کانال بسازید و آن را در همهٔ RPCها دوباره استفاده کنید. برای هر درخواست یک اتصال جدید نسازید.

برای عملیات انبوه از جریان‌سازی استفاده کنید

برای عملیات دسته‌ای، RPCهای جریان‌سازی سمت کلاینت یا دوطرفه را به فراخوانی‌های مکرر یک‌طرفه ترجیح دهید. StreamIndicators ده برابر سریع‌تر از فراخوانی CheckIndicator در یک حلقه است.

مهلت‌ها را تعیین کنید

همیشه مهلت‌های زمینه را تعیین کنید. یک پیش‌فرض منطقی، ۳۰ ثانیه برای RPCهای یک‌طرفه و ۵ دقیقه برای RPCهای جریان‌سازی است. بدون مهلت، RPCهای گیرکرده منابع را نشت می‌دهند.

Keepalive را فعال کنید

پارامترهای keepalive مربوط به gRPC را پیکربندی کنید تا از بسته‌شدن اتصال‌های بی‌کار توسط پراکسی‌های میانی جلوگیری شود. زمان keepalive را روی ۳۰ ثانیه و وقفهٔ زمانی را روی ۱۰ ثانیه تنظیم کنید.


با gRPC بسازید

از APIهای پرکارایی gRPC سرویس OrbVPN برای شبکه‌سازی مش، مدیریت تونل VPN و اطلاعات تهدید بی‌درنگ بهره ببرید. نوع‌دهی‌شدهٔ قوی، فوق‌العاده سریع و آمادهٔ تولید.

مشاهدهٔ SDKها