Англійська для розробників gRPC-Web

gRPC-Web дозволяє клієнтам браузера спілкуватися з службами gRPC, але це не сам gRPC — це обмежений протокол, який потребує проксі для перекладу до і з справжнього HTTP/2 gRPC, і він підтримує тільки підмножину режимів потокового передачі. Команди, які вважають, що gRPC-Web поводиться ідентично до backend-to-backend gRPC, стикаються з заплутаними прогалинами, особливо навколо двостороннього потоку. Цей підручник містить інформацію англійською мовою, яку використовують під час обговорення gRPC- Web з командою.

Ключовий словник

Envoy proxy (рівень перекладу) — посередник (зазвичай Envoy або подібний проксі), який знаходиться між браузером і backend gRPC, перекладаючи gRPC-Web HTTP/1.1-сумісне фреймування на справжні HTTP/2 gRPC виклики. “Браузер не може говорити сирий HTTP/2 gRPC безпосередньо — саме тому нам потрібен шар перекладу Envoy перед бекендом.”

** Серверний поток (підтримується) ** — єдиний режим потоку, який gRPC- Web повністю підтримує з переглядача: сервер може відсилати послідовність повідомлень за допомогою одного запиту. “Стриминг сервера працює добре — клієнт відкриває один запит і просто продовжує отримувати шматки, коли вони генеруються.”

** Клієнт/ двосторонній поток (не підтримується) ** — режими потоку, які gRPC- Web не підтримує в браузері; клієнт не може тримати поток відкритим і надсилати декілька повідомлень, як це можливо у backend- to- backend gRPC. “Ми не можемо перенести цю двосторонню функцію чату на gRPC-Web як є — браузер не може передавати потокові запити, тільки отримувати потоки назад, тому нам потрібні WebSockets або інший шаблон для вивантаження.”

** Codegen / stub ** — сформований клієнтський код (« stub ») створений з файла .proto компілятором буфера протоколу, що надає інтерфейсу типові методи замість написаних вручну викликів отримання.

• “Відновити заголовок після зміни файла .proto — інтерфейс все ще викликає метод, який більше не відповідає оновленому визначення служби.” *

** Trailer ** — метадані, надіслані після тіла відповіді у виклику gRPC (зазвичай, код кінцевого стану), які gRPC- Web має контрабандувати інакше, ніж рідний gRPC, оскільки браузери не можуть читати HTTP- трейлери безпосередньо. “Код стану надходить у трейлері, а не в звичайному заголовку — саме тому ви не можете просто перевірити response.status так, як ви б це зробили з простим викликом REST.”

** Перехоплювач ** — це гачок на стороні клієнта або проксі- сервера, який виконується під час кожного виклику (додавання токенів автентифікації, ведення журналу, повторення спроб) без зміни кожного з створених методів заголовка окремо.

• “Додати токен автентифікації у перехоплювач клієнта замість редагування кожного сформованого методу вручну — вивід codegen не потребує вручну вносити зміни.” *

Звичайні фрази

• «Чи це виклик сервера-стрімінгу, чи йому потрібен справжній двосторонній стримінг, який gRPC-Web не може зробити з браузера?»
• «Чи ми відновили заголовок після останньої зміни .proto, або ж інтерфейс все ще викликає старий підпис?»
• «Де проксі-рівень перекладу сидить в цьому розгортанні — sidecar, gateway, або load balancer?»
• Чи код стану надходить правильно, чи щось їсть трейлер?»
• Чи варто цю проблему вирішувати в клієнтовому перехоплювачі, а не на кожному сайті з викликами?»

Приклади висловлювань

Перегляд запиту на звантаження: “Це намагається відкрити постійний двосторонній потік з браузера — gRPC-Web не може зробити це на рідній мові, тому нам доведеться перепроектувати це як запит/відповідь або серверний потік.”

Пояснення рішення про проектування: “Ми поставили проксі Envoy перед backend gRPC спеціально для перекладу gRPC-Web трафіку — браузер ніколи не розмовляє HTTP/2 gRPC безпосередньо.”

Опис події: “Клієнт беззвучно зазнав невдачі, оскільки він читав response.status безпосередньо замість аналізу трейлерів, де gRPC-Web фактично вставляє справжній код стану.”

Професійні поради

• Скажіть “gRPC-Web не підтримує клієнтський потоковий доступ” точно, а не “потоковий доступ пошкоджений” — це називає фактичне обмеження і уникає того, щоб хтось переслідував ваду, якої там немає.
• Коли пропонується нова кінцева точка, що звернена до браузера, запитайте “чи потрібна двостороння потокова передача?” на початку - це визначає, чи gRPC-Web навіть дійсний для цієї функції.
• Використовуйте “stub” і “codegen” навмисно, коли обговорюєте сформований клієнтський код — це пояснює, що код не повинен бути редагований вручну, а тільки відновлений.
• Згадайте “трейлер” явно під час зневадження кодів стану — більшість інженерів REST-фонова не думають, щоб подивитися там спочатку.

Практичні вправи

1. Поясніть двома реченнями, чому gRPC- Web потрібен проксі- шар перекладу перед сервером.
2. Написати коментар перегляду коду у одному реченні, у якому рекомендується переробити функцію, оскільки для її використання потрібна двостороння потокова передача, яка не підтримується.
3. Опишете вашими словами відмінність між заголовком і трейлером у відповіді gRPC- Web.

На практиці: Навігація нюансів в спільному розвитку

Як не рідною мовою англійською, особливо коли зосереджені на технічний жаргон, як це використовується в рамках gRPC-Web розробки, це легко відчувати пригніченість тонкими нюансами і улюбленими фразами. Це не просто про те, щоб знати * що * щось означає; це про те, щоб передавати своє розуміння чітко і ефективно вносити вклад в командне середовище. Часто, найбільш розчаруючим аспектом є не одне слово, а неявні очікування, що оточують спілкування - як ви обробляєте проблеми, запитуєте зміни або пояснюєте свої міркування. Давайте розглянемо кілька реалістичних сценаріїв.

Уявіть, що ви переглядаєте запит на витягування, надісланий колегою, який вводить нове обмеження потоку у службі gRPC- Web. Їхній PR-опис просто говорить: «Додано обмеження потоків». Хоча це технічно правильно, в цьому немає важливого контексту. Корисною відповіддю може бути: «Це добре, що ми звертаємо увагу на потенційний зворотній тиск! Чи можете ви роз’яснити, чому вибрали саме ці обмеження? Було б корисно документувати логіку, що стоїть за ними – можливо, посилаючись [на посилання на відповідну документацію або дискусійну гілочку] – щоб інші розуміли, що це за компроміс. Зокрема, чи могли б ви додати коментар, у якому пояснили б, як це впливає на затримку клієнта і чи планується спостереження за цим ефектом?» Зауважте, що зміна від простого вказівки на проблему (« Додано обмеження потоків ») до конструктивного запиту на пояснення і подальші відомості. Використання таких фраз, як «це було б вигідно», «вплине на latency клієнта», і «моніторинг планується» демонструє глибше розуміння складності системи і позитивно впливає на процес перегляду.

Інша поширена ситуація виникає в розмовах Slack. Припустимо, що ви обговорюєте потенційне вузьке місце з іншим розробником, і він відповідає: « Виклики gRPC повільні ». Це твердження, хоча і зрозуміле, не є дієздатним. Ефективнішою відповіддю було б: « Чи можете ви надати деякі деталі про те, * які * виклики gRPC виявляють затримку? Чи ми бачимо це послідовно у всіх клієнтах, чи це специфічно для певної версії переглядача або стану мережі? Чи можете ви, можливо, запустити grpc_trace проти проблематичного виклику і поділитись вихідним кодом для аналізу?» (інструмент grpc_trace допомагає діагностувати проблеми з продуктивністю в системах gRPC). Цей підхід виходить за межі неясних спостережень і направляє увагу на збір конкретних даних.

Нарешті, розгляньте можливість створення опису PR, коли ви пропонуєте зміни до вашого власного коду. Замість простого повідомлення « Виправлено помилку » ви можете написати: « Виправлено проблему, коли клієнт періодично відкидав запити через перевищення максимальної тривалості потоку. Впроваджено механізм керування потоком, щоб зменшити цю проблему [коротко описати рішення — наприклад, обмеження частоти запитів на основі обсягу сервера]. Ця зміна вирішує проблему потенційного зворотного тиску і покращує загальну стабільність системи. Рішення про впровадження контролю потоку було оголошено за даними моніторингу, що вказують на [згадати конкретні показники]». Такий рівень деталізації показує власника, пояснює обґрунтування виправлення і чітко повідомляє про вплив зміни.

# Example using gRPC trace (simplified)
grpc_trace --client-url https://api.example.com/my-service --server-url https://api.example.com/my-service -o trace.json

За допомогою цієї команди можна запустити сеанс відстеження, за допомогою якого буде записано подробиці щодо зв’ язку gRPC між клієнтом і сервером. Аналіз виводу trace.json (зазвичай, використовуючи такі інструменти, як grpc_tracer ) дозволяє розробникам ідентифікувати вузли продуктивності і зрозуміти потік даних в системі. Навчання чітко формулювати ці технічні спостереження англійською мовою є ключем до безперервної співпраці в команді розробників gRPC-Web.