Buf(1) Buf(1)

buf-curl - فراخوانی نقاط پایانی RPC با پروتکل‌های HTTP/gRPC توسط buf

buf curl [flags]

این دستور به شما در فراخوانی نقاط پایانی RPC مبتنی بر HTTP در سروری که از gRPC یا Connect استفاده می‌کند، کمک می‌کند.

به طور پیش‌فرض، از بازتاب سرور (server reflection) استفاده می‌شود، مگر اینکه گزینه --reflect بر روی false تنظیم شده باشد. بدون بازتاب سرور، باید گزینه --schema ارائه شود تا طرح‌واره (schema) پروتوباف (Protobuf) مربوط به متد در حال فراخوانی را مشخص کند.

تنها آرگومان موضعی، نشانی اینترنتی (URL) متد RPC برای فراخوانی است. نام متد مورد نظر برای فراخوانی از دو بخش پایانی مسیر URL حاصل می‌شود که باید به ترتیب شامل نام کاملاً مشخص سرویس (fully-qualified service name) و نام متد باشد.

نشانی اینترنتی (URL) می‌تواند از طرح (scheme) http یا https استفاده کند. در صورت استفاده از http، پروتکل HTTP 1.1 استفاده خواهد شد مگر اینکه گزینه --http2-prior-knowledge تنظیم شده باشد. اگر از https استفاده شود، HTTP/2 در طول مذاکره پروتکل در اولویت خواهد بود و از HTTP 1.1 تنها در صورتی استفاده می‌شود که سرور از HTTP/2 پشتیبانی نکند.

پروتکل پیش‌فرض RPC مورد استفاده Connect خواهد بود. برای استفاده از پروتکلی دیگر (gRPC یا gRPC-Web)، از گزینه --protocol استفاده کنید. توجه داشته باشید که پروتکل gRPC نمی‌تواند با HTTP 1.1 استفاده شود.

درخواست ورودی از طریق گزینه -d یا --data مشخص می‌شود. در صورت عدم وجود آن، یک درخواست خالی ارسال می‌شود. اگر مقدار گزینه با علامت ات‌ساین (@) شروع شود، باقی‌مانده مقدار گزینه به عنوان نام فایلی تفسیر می‌شود که بدنه درخواست از آن خوانده خواهد شد. اگر نام فایل فقط یک خط تیره (-) باشد، بدنه درخواست از ورودی استاندارد (stdin) خوانده می‌شود. بدنه درخواست یک سند JSON است که شامل پیام درخواست قالب‌بندی‌شده به صورت JSON است. اگر متد RPC در حال فراخوانی از نوع جریان کلاینت (client-streaming) باشد، بدنه درخواست می‌تواند شامل چندین مقدار JSON باشد که پشت سر هم اضافه شده‌اند. چندین سند JSON معمولاً باید با فاصله‌های خالی (whitespace) از یکدیگر جدا شوند، هرچند این امر اکیداً الزامی نیست مگر اینکه نوع پیام درخواست دارای یک نمایش سفارشی JSON باشد که شیء (object) JSON نباشد.

متاداده درخواست (یعنی هدرها) با استفاده از گزینه‌های -H یا --header تعریف می‌شوند. مقدار گزینه در قالب "name: value" است. اما اگر با علامت ات‌ساین (@) شروع شود، باقی‌مانده مقدار به عنوان نام فایلی تفسیر می‌شود که هدرها از آن خوانده می‌شوند (هر هدر در یک خط جداگانه). اگر نام فایل تنها یک خط تیره (-) باشد، هدرها از ورودی استاندارد (stdin) خوانده خواهند شد.

اگر قرار باشد هم هدرها و هم بدنه درخواست از یک فایل خوانده شوند (یا هر دو از stdin خوانده شوند)، فایل ابتدا باید شامل هدرها، سپس یک خط خالی و پس از آن بدنه درخواست باشد.

مثال‌ها:

ارسال یک RPC یک‌طرفه (unary) به سرور متنی ساده gRPC (به اصطلاح "h2c")، که طرح‌واره سرویس در یک ماژول Buf در دایرکتوری فعلی قرار دارد، با استفاده از یک پیام درخواست خالی:

$ buf curl --schema . --protocol grpc --http2-prior-knowledge \
     http://localhost:20202/foo.bar.v1.FooService/DoSomething

ارسال یک RPC به یک سرور Connect، که در آن طرح‌واره از رجیستری شمای Buf می‌آید، با استفاده از درخواستی که به عنوان یک آرگومان خط فرمان تعریف شده است:

$ buf curl --schema buf.build/connectrpc/eliza \
     --data '{"name": "Bob Loblaw"}' \
     https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Introduce

ارسال یک RPC یک‌طرفه (unary) به سروری که از بازتاب پشتیبانی می‌کند، با خروجی پرجزئیات:

$ buf curl --data '{"sentence": "I am not feeling well."}' -v \
     https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say

ارسال یک RPC مبتنی بر جریان سمت کلاینت (client-streaming) به یک سرور gRPC-web که از بازتاب پشتیبانی می‌کند، که در آن هدرهای سفارشی و داده‌های درخواست هر دو در یک heredoc قرار دارند:

$ buf curl --data @- --header @- --protocol grpcweb \
     https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Converse \
   <<EOM
Custom-Header-1: foo-bar-baz
Authorization: token jas8374hgnkvje9wpkerebncjqol4
{"sentence": "Hi, doc. I feel hungry."}
{"sentence": "What is the answer to life, the universe, and everything?"}
{"sentence": "If you were a fish, what of fish would you be?."}
EOM

توجه داشته باشید که بازتاب سرور (یعنی استفاده از گزینه --reflect) با HTTP 1.1 کار نمی‌کند زیرا پروتکل به جریان دوطرفه (bidirectional streaming) متکی است. اگر از بازتاب سرور استفاده شود، نشانی فرضی URL برای سرویس بازتاب همان URL داده‌شده است، با این تفاوت که دو بخش پایانی حذف شده و با نام سرویس و متد مربوط به بازتاب سرور جایگزین می‌شوند.

در صورت وقوع خطایی ناشی از استفاده نادرست یا خطای غیرمنتظره دیگر، این برنامه یک کد خروج کمتر از ۸ برمی‌گرداند. در غیر این صورت اگر RPC با شکست مواجه شود، این برنامه کد خروجی برابر با کد gRPC را که سه بیت به چپ شیفت داده شده است برمی‌گرداند.

--cacert="" مسیر فایل مجموعه گواهی X509 با کدگذاری PEM که شامل مجموعه‌ای از مرجع‌ها/صادرکنندگان گواهی معتبر است. در صورت حذف، از مجموعه پیش‌فرض گواهی‌های معتبر سیستم برای تأیید گواهی سرور استفاده می‌شود. این گزینه تنها زمانی معتبر است که URL از پروتکل https استفاده کند. در صورت استفاده از گزینه --insecure یا -k این گزینه قابل اعمال نیست

-E, --cert="" مسیر فایل گواهی X509 با کدگذاری PEM، جهت استفاده از گواهی‌های کلاینت با TLS. این گزینه تنها زمانی معتبر است که URL از پروتکل https استفاده کند. گزینه --key نیز باید برای ارائه کلید خصوصی متناظر با گواهی داده‌شده وجود داشته باشد

--connect-timeout=0 محدودیت زمانی (بر حسب ثانیه) برای برقراری اتصال با سرور. در صورت عدم وجود این گزینه، هیچ محدودیتی وجود ندارد

-d, --data="" داده‌های درخواست. این باید صفر یا چند سند JSON باشد که هر کدام نشان‌دهنده یک پیام درخواست است. برای RPCهای یک‌طرفه (unary)، باید دقیقاً یک سند JSON وجود داشته باشد. مقدار ویژه '@' به معنای خواندن داده‌ها از فایل در مسیر مشخص‌شده است. اگر مسیر "-" باشد، داده‌های درخواست از stdin خوانده می‌شود. اگر فایلی مشابه با آنچه برای گزینه‌های هدرهای درخواست (--header یا -H) استفاده شده مشخص شود، فایل باید ابتدا شامل تمام هدرها، سپس یک خط خالی و پس از آن بدنه درخواست باشد. در صورتی که انتظار می‌رود طرح‌واره از طریق stdin به عنوان یک مجموعه توصیف‌کننده فایل (file descriptor set) یا ایمیج ارائه شود، مشخص کردن stdin برای داده مجاز نیست

--emit-defaults[=false] درج مقادیر پیش‌فرض برای پاسخ‌های کدگذاری‌شده با JSON.

-H, --header=[] هدرهای درخواست برای گنجاندن در فراخوانی RPC. این گزینه را می‌توان بیش از یک بار برای مشخص کردن چندین هدر تعیین کرد. مقدار هر گزینه باید به فرمت "name: value" باشد. مقدار ویژه به معنای خواندن هدرها از فایل در مسیر مشخص‌شده است. اگر مسیر "-" باشد، هدرها از stdin خوانده می‌شوند. اگر فایلی مشابه با آنچه با گزینه داده‌های درخواست (--data یا -d) استفاده شده مشخص شود، فایل باید ابتدا شامل تمام هدرها، سپس یک خط خالی و پس از آن بدنه درخواست باشد. در صورتی که انتظار می‌رود طرح‌واره از طریق stdin به عنوان یک مجموعه توصیف‌کننده فایل یا ایمیج ارائه شود، مشخص کردن stdin مجاز نیست

-h, --help[=false] راهنمای curl

--http2-prior-knowledge[=false] این گزینه می‌تواند برای نشان دادن استفاده از HTTP/2 استفاده شود. بدون این گزینه، برای URLهای با پروتکل http از HTTP 1.1 استفاده خواهد شد و برای URLهای با پروتکل https از مذاکره پروتکل برای انتخاب بین HTTP 1.1 یا HTTP/2 استفاده می‌شود. با تنظیم این گزینه، همیشه از HTTP/2 استفاده خواهد شد، حتی روی متن ساده (plain-text).

--http3[=false] این گزینه می‌تواند برای نشان دادن استفاده از HTTP/3 استفاده شود. بدون این گزینه، برای URLهای با پروتکل http از HTTP 1.1 استفاده خواهد شد و برای URLهای با پروتکل https از مذاکره پروتکل برای انتخاب بین HTTP 1.1 یا HTTP/2 استفاده می‌شود. با تنظیم این گزینه، همیشه از HTTP/3 استفاده می‌شود.

-k, --insecure[=false] در صورت تنظیم، اتصال TLS ناامن خواهد بود و گواهی سرور تأیید نخواهد شد. استفاده از این حالت عموماً توصیه نمی‌شود. این گزینه تنها زمانی معتبر است که URL از پروتکل https استفاده کند

--keepalive-time=60 مدت زمان (بر حسب ثانیه) بین ارسال‌های TCP keepalive

--key="" مسیر فایل کلید خصوصی X509 با کدگذاری PEM، جهت استفاده از گواهی‌های کلاینت با TLS. این گزینه تنها زمانی معتبر است که URL از پروتکل https استفاده کند. گزینه --cert یا -E نیز باید برای ارائه گواهی و کلید عمومی متناظر با کلید خصوصی داده‌شده وجود داشته باشد

--list-methods[=false] در صورت تنظیم، دستور متدهای پشتیبانی‌شده را فهرست کرده و سپس خارج می‌شود. اگر از بازتاب سرور برای ارائه طرح‌واره RPC استفاده شود، URL داده‌شده باید یک URL پایه باشد و شامل نام سرویس یا متد نباشد. اگر منبع طرح‌واره بازتاب سرور نباشد، URL استفاده نمی‌شود و می‌تواند حذف شود.

--list-services[=false] در صورت تنظیم، دستور سرویس‌های پشتیبانی‌شده را فهرست کرده و سپس خارج می‌شود. اگر از بازتاب سرور برای ارائه طرح‌واره RPC استفاده شود، URL داده‌شده باید یک URL پایه باشد و شامل نام سرویس یا متد نباشد. اگر منبع طرح‌واره بازتاب سرور نباشد، URL استفاده نمی‌شود و می‌تواند حذف شود.

-n, --netrc[=false] اگر true باشد، فایلی به نام .netrc در دایرکتوری خانگی کاربر برای یافتن اعتبارنامه‌های درخواست بررسی خواهد شد. این اعتبارنامه‌ها از طریق هدر احراز هویت اولیه ارسال خواهند شد. اگر فایل فاقد مدخلی برای نام میزبان در URL باشد، دستور با شکست مواجه می‌شود. در صورت وجود گزینه --user یا -u، این گزینه نادیده گرفته می‌شود. همچنین اگر گزینه‌ای مانند --header یا -H ارائه شده باشد که هدری به نام 'Authorization' را تنظیم کند، این گزینه نادیده گرفته می‌شود.

--netrc-file="" این گزینه دقیقاً مانند استفاده از --netrc یا -n است، با این تفاوت که به جای فایل .netrc در دایرکتوری خانگی کاربر، از فایل مشخص‌شده استفاده می‌شود. این گزینه را نمی‌توان همراه با گزینه --netrc یا -n به کار برد. در صورتی که گزینه --header یا -H ارائه شده باشد که هدری به نام 'Authorization' را تنظیم کند، این گزینه نادیده گرفته می‌شود.

--no-keepalive[=false] به طور پیش‌فرض، اتصالات با استفاده از TCP keepalive ایجاد می‌شوند. در صورت وجود این گزینه، آنها غیرفعال خواهند شد

-o, --output="" مسیر فایل خروجی برای ایجاد با داده‌های پاسخ. در صورت عدم وجود، پاسخ در stdout چاپ می‌شود

--protocol="connect" پروتکل RPC برای استفاده. این مقدار می‌تواند یکی از "grpc"، "grpcweb" یا "connect" باشد

--reflect[=true] اگر true باشد، از بازتاب سرور برای تعیین طرح‌واره استفاده می‌شود

--reflect-header=[] هدرهای درخواست برای گنجاندن در درخواست‌های بازتاب. این گزینه تنها زمانی قابل استفاده است که --reflect نیز تنظیم شده باشد. این گزینه می‌تواند بیش از یک بار برای مشخص کردن چندین هدر تعیین شود. مقدار هر گزینه باید به فرمت "name: value" باشد. اما مقدار ویژه '*' می‌تواند برای نشان دادن این موضوع استفاده شود که تمام هدرهای معمولی درخواست (از گزینه‌های --header و -H) نیز باید در درخواست‌های بازتاب گنجانده شوند. مقدار ویژه '@' به معنای خواندن هدرها از فایل در مسیر مشخص‌شده است. اگر مسیر "-" باشد، هدرها از stdin خوانده می‌شوند. مشخص کردن فایلی با همان مسیری که با گزینه داده‌های درخواست (--data یا -d) استفاده شده مجاز نیست. علاوه بر این، در صورتی که انتظار می‌رود طرح‌واره از طریق stdin به عنوان یک مجموعه توصیف‌کننده فایل یا ایمیج ارائه شود، مشخص کردن stdin مجاز نیست

--reflect-protocol="" پروتکل بازتاب برای استفاده جهت دریافت اطلاعات از سرور. این گزینه تنها زمانی قابل استفاده است که از بازتاب سرور استفاده شود. به طور پیش‌فرض، این دستور تمام پروتکل‌های بازتاب شناخته‌شده را از جدیدترین به قدیمی‌ترین امتحان می‌کند. اگر این کار منجر به خطای "Not Implemented" شود، از پروتکل‌های قدیمی‌تر استفاده خواهد شد. در عمل، این بدان معناست که ابتدا "grpc-v1" امتحان می‌شود و در صورت عدم موفقیت، از "grpc-v1alpha" استفاده خواهد شد. اگر پروتکل‌های بازتاب جدیدتری معرفی شوند، در صورت عدم تنظیم صریح این گزینه روی یک پروتکل خاص، ممکن است در اولویت قرار گیرند. مقادیر معتبر برای این گزینه "grpc-v1" و "grpc-v1alpha" هستند. این مقادیر به ترتیب متناظر با سرویس‌هایی به نام "grpc.reflection.v1.ServerReflection" و "grpc.reflection.v1alpha.ServerReflection" هستند

--schema=[] ماژول مورد استفاده برای طرح‌واره RPC. در صورتی که سرور از بازتاب سرور پشتیبانی نکند، این گزینه ضروری است. قالب این آرگومان همانند آرگومان‌های سایر زیردستورات buf مانند build و generate است. می‌تواند یک دایرکتوری، یک فایل، یک ماژول دوردست در رجیستری شمای Buf یا حتی ورودی استاندارد ("-") برای ارسال یک ایمیج یا مجموعه توصیف‌کننده فایل به دستور در یک خط لوله پوسته (shell pipeline) را مشخص کند. اگر چندین گزینه schema وجود داشته باشد، آنها به ترتیب برای تطبیق نام‌های سرویس و نوع بررسی می‌شوند. تنظیم این گزینه به معنای --reflect=false است، مگر اینکه گزینه reflect به طور صریح وجود داشته باشد. اگر هر دو گزینه schema و reflect در حال استفاده باشند، ابتدا از بازتاب استفاده خواهد شد و در صورتی که بازتاب نتواند یک عنصر طرح‌واره را تطبیق دهد، طرح‌واره‌ها پس از آن به ترتیب بررسی خواهند شد.

--servername="" نام سرور برای استفاده در مصافحه‌های TLS (برای SNI) در صورتی که طرح URL از نوع https باشد. در صورت عدم تعیین، مقدار پیش‌فرض میزبان مبدأ در URL یا مقدار موجود در هدر "Host" (در صورت ارائه) است

--unix-socket="" مسیر سوکت یونیکس که به جای باز کردن یک سوکت TCP به میزبان و پورت مشخص‌شده در URL استفاده خواهد شد

-u, --user="" اعتبارنامه کاربر برای ارسال از طریق هدر احراز هویت اولیه. مقدار باید در قالب "username:password" باشد. اگر مقدار فاقد دونقطه باشد، فرض می‌شود که فقط نام کاربری است که در این صورت از شما خواسته می‌شود رمز عبور را وارد کنید. این گزینه بر استفاده از فایل .netrc اولویت دارد. در صورتی که گزینه --header یا -H ارائه شده باشد که هدری به نام 'Authorization' را تنظیم کند، این گزینه نادیده گرفته می‌شود.

-A, --user-agent="" رشته عامل کاربر (user agent) برای ارسال. در صورتی که گزینه --header یا -H ارائه شده باشد که هدری به نام 'User-Agent' را تنظیم کند، این گزینه نادیده گرفته می‌شود.

-v, --verbose[=false] فعال کردن حالت پرجزئیات

--debug[=false] فعال کردن گزارش اشکال‌زدایی (debug)

--log-format="color" قالب گزارش [text,color,json]

--timeout=0s مدت زمان تا پایان مهلت زمانی؛ تنظیم آن بر روی 0s به معنای بدون محدودیت زمانی است

buf(1)

2026-07-17 تولید خودکار توسط spf13/cobra

2026-07-17 Auto generated by spf13/cobra