عن المشروع

grpc-web هو تطبيق JavaScript لـ gRPC لعملاء المتصفح، يُصان ضمن مستودع grpc/grpc-web. ولأن المتصفحات لا تستطيع فتح اتصالات gRPC خام عبر HTTP/2، يتحدث عملاء gRPC-web إلى خدمات gRPC عبر وسيط خاص؛ وEnvoy هو الوسيط الافتراضي، كما يوثق المشروع التوافق التشغيلي مع وسيط gRPC-web Go وApache APISIX ووحدة gRPC في Nginx. يوفر المشروع مكونين رئيسيين. أولاً، مكتبة وقت تشغيل منشورة على npm باسم `grpc-web`، وهي مكتوبة الآن بالكامل بـ TypeScript وبالتالي توفر أمان أنواع من الدرجة الأولى، وصفر تبعيات وقت تشغيل، وتعريفات أنواع مدمجة. ثانياً، إضافة protoc باسم `protoc-gen-grpc-web` تولد stubs لخدمة العميل من تعريفات `.proto`. وعادةً ما يقترن التوليد بإضافة `--js_out` القياسية (لفئات رسائل protobuf) مع `--grpc-web_out` (لـ stub الخدمة)، ويمكن تجميعه باستخدام Browserify أو Webpack أو Closure Compiler. أوضاع RPC المدعومة هي الاستدعاءات الأحادية والبث من جانب الخادم. ويتوفر البث من جانب الخادم فقط في وضع تنسيق النقل `grpcwebtext`، حيث تُرمّز الحمولات بـ base64 وتُرسل مع `Content-Type: application/grpc-web-text`. أما الوضع الثنائي `grpcweb` فيستخدم `Content-Type: application/grpc-web+proto` مع حمولات protobuf ثنائية لكنه يدعم الاستدعاءات الأحادية فقط. ولا يُدعم حالياً البث من جانب العميل أو البث ثنائي الاتجاه. يوفر توليد الشيفرة عدة أنماط استيراد: `closure` (الافتراضي، باستخدام `goog.require()`)، و`commonjs` (باستخدام `require()`)، و`commonjs+dts` (stubs بنمط CommonJS مع ملف تعريفات `.d.ts`)، و`typescript` (مخرجات TypeScript كاملة). ولا يدعم نمطي `commonjs+dts` و`typescript` إلا `--grpc-web_out`، وليس `--js_out`. ويتضمن README مثالاً ملموساً لتوليد شيفرة TypeScript باستخدام تنسيق النقل الثنائي، ما ينتج عميل خدمة TypeScript ووحدة protobuf JavaScript وملف تعريف `.d.ts` مطابقاً. استخدام العميل مباشر: أنشئ عميل خدمة بعنوان URL للوسيط، وابنِ رسالة طلب، ثم استدعِ RPC مع بيانات وصفية اختيارية ودالة callback. ويعيد البث من جانب الخادم كائن stream مع أحداث `data` و`status` و`end`، إضافة إلى طريقة `cancel()`. ويمكن تعيين موعد نهائي بتمرير ترويسة `deadline` تحتوي على طابع زمني Unix بالمللي ثانية. ويتوفر نمطان للعميل: عملاء قائمون على callback وعملاء قائمون على Promise، لكن نسخة Promise لا يمكنها الوصول إلى callbacks `.on(...)` للبيانات الوصفية والحالة. يمكن تنفيذ معترضات مخصصة وربطها لتوفير ميزات مثل المصادقة وإعادة المحاولات. ويوجد نوعان من المعترضات: `UnaryInterceptor`، الذي يعترض استدعاءات RPC الأحادية ولا يمكن استخدامه إلا مع عملاء Promise، و`StreamInterceptor`، وهو أكثر مرونة ويعمل مع العملاء العاديين. يتضمن المستودع مثال Hello World يستعرض تعريف خدمة باستخدام protocol buffers، وتنفيذ خدمة gRPC بـ Node.js، وتهيئة وسيط Envoy، وتوليد فئات protobuf وstubs العميل، وتجميع تبعيات JS في مكتبة ثابتة. ويمكن تشغيل عرض Echo أكثر تقدماً باستخدام Docker Compose، وهو يعرض صفحة متصفح للاختبار والبث. ويشير README أيضاً إلى تكاملات المنظومة، بما في ذلك أطر خوادم Armeria (JVM) وTonic (Rust) مع دعم gRPC-web، وعرض توافق مع Vite. وتوضح وثيقة خارطة طريق الأعمال المستقبلية، بما في ذلك دعم أطر الويب الخاصة بلغات Python وJava وNode.