בדף הזה מפורטים טיפים לכתיבת תוספים של Service Extensions שהם נכונים, פועלים בצורה טובה ומבודדים היטב. הדיוק הוא קריטי כי התוספים פועלים בארגז חול מוגבל של מנוע עם פלטפורמת API מוגבלת. הביצועים הם קריטיים כי התוספים פועלים במהלך בקשות של משתמשי קצה, עם כמויות קטנות של משאבים. הבידוד מסופק ברמת הפרויקט.
תחילת העבודה
התחלה מהדוגמאות
דרך טובה להתחיל היא לעיין בדוגמאות לקוד של תוספים. אלה דוגמאות לדפוסי תוספים נפוצים, כמו ניתוח נתיבים או שאילתות, שינוי כותרות, רישום ביומן בהתאמה אישית ואימות בהתאמה אישית.
שימוש בממשקי API נתמכים
צריך לקמפל את הפלאגינים מול הממשק הבינארי (ABI) של Proxy-Wasm. התוספים לשירות תומכים בחלק מה-ABI של Proxy-Wasm, שכולל שינויים בכותרת ובגוף של HTTP, תגובות מקומיות, רישום מותאם אישית ביומן והגדרת פלאגין. Proxy-Wasm תומך גם בקבוצת משנה קטנה של WASI preview 1, כולל stdout ו-stderr לרישום ביומן, clock_time_get ו-random_get.
Service Extensions לא תומכים בטיימרים, במדדים מותאמים אישית, בנתונים משותפים, בתורים משותפים או בשיחות יוצאות ברשת. בנוסף, Service Extensions לא תומכים בערכי החזרה של קריאות חוזרות (callback) של תוספים שמנסים להשהות את עיבוד הבקשה, והם מתעלמים מהם.
הפעלת בדיקות פונקציונליות ובדיקות השוואה
כדי להעריך את הנכונות והביצועים, אנחנו מספקים כלי מקומי לבדיקת פלאגינים שיכול להריץ, לבדוק ולהשוות את הפלאגין שלכם. מפעילים את הכלי הזה בקונטיינר Docker, ומעבירים לו קובץ בינארי של פלאגין ופרוטוקול טקסט של קלט וציפיות. אפשר לעיין במסמכי התיעוד של הכלי לבדיקה מקומית ובדוגמה לקלט לבדיקה.
נכונות
אל תסתמכו על שעונים
מטעמי אבטחה, השעה מוגדרת בזמן יצירת ההקשר (עבור פלאגין או בקשה) ונשארת קבועה במהלך הפעלת הפלאגין. המשמעות היא שאסור לתוספים של WebAssembly להיכנס למצב שינה. מצב שינה יפוג כי הזמן לא מתקדם. זה גם אומר שתוספים לא יכולים למדוד את זמן הביצוע שלהם, אבל המידע הזה זמין ב-Cloud Monitoring.
התייחסות לשמות של כותרות כלא תלויי-רישיות
לפי הסמנטיקה של HTTP, צריך להתייחס לשמות של שדות כותרת HTTP כאל שמות לא תלויי-רישיות. אפשר לשנות את האותיות בכותרת שנכתבה על ידי תוסף לפני שהיא נשלחת ללקוחות או לשרתי קצה עורפיים.
ביצועים
איך למנוע קריסות של תוספים
קומפילציה לשיפור מהירות הביצוע
קומפילציה מראש של ביטויים רגולריים
איך להימנע מהעתקת נתונים להקשרים של HTTP
איך נמנעים מקריסות של פלאגינים
כשתוסף קורס, הבקשה שגרמה לקריסה מקבלת שגיאה. אם זה קורה לעיתים קרובות, המערכת מגבילה את ההפעלה מחדש של התוסף, מה שמוביל לפרצי שגיאות שמשפיעות על כמה משתמשים.
כדי למנוע קריסות של פלאגינים, אפשר לנסות את הפעולות הבאות:
- אל תשתמשו בהצהרות מכל סוג שהוא. במקום זאת, כדאי להגדיר רישום שגיאות או תגובות מקומיות למשתמשים.
- ב-Rust, כדאי להימנע משימוש בשיטות כמו
unwrap, שעלולות לגרום ל-panics. בנוסף, אתם יכולים להגדיר את הפלאגין לטיפול בקריסות באמצעותpanic::set_hook. - כדי לבדוק את הפלאגין, משתמשים בכלי לבדיקת פלאגינים ש-Google מספקת, ומוודאים שהפלאגין מטפל בקלט לא תקין או ריק בלי לקרוס.
קומפילציה למהירות ביצוע
כדי להשיג את מהירות הביצוע הטובה ביותר, צריך לקמפל את קוד WebAssembly באמצעות אפשרות הבנייה -O3 (ל-C++) או opt-level=3 (ל-Rust).
קומפילציה מראש של ביטויים רגולריים
מומלץ להימנע מפעולות שדורשות הרבה משאבי מחשוב בנתיב של כל בקשה (במטפלי HTTP). במקום זאת, מבצעים את כל הפעולות שלא קשורות לבקשה בזמן ההגדרה של התוסף, ומעבירים כל מצב שחושב מראש לכל הקשר של בקשת HTTP (שנקרא גם הקשר של הזרם).
בפרט, צריך לבצע קומפילציה מראש של כל הביטויים הרגולריים בזמן ההגדרה של התוסף. בדוגמת הקוד של הביטוי הרגולרי אפשר לראות איך עושים את זה.
הימנעו מהעתקת נתונים להקשרי HTTP
כשמשתפים נתונים בין הקשר הבסיסי לבין הקשרי HTTP, כדאי להימנע מהעתקות יקרות או מקריאות שיבוט. במקום זאת, אפשר לשתף רמזים או הפניות. ב-C++, אפשר לעשות את זה באמצעות std::shared_ptr או הפניות והמצביעים הגולמיים, כי הקשר הבסיסי נשאר פעיל אחרי שהקשר של ה-HTTP מסתיים. ב-Rust, אפשר לשתף ערכים באמצעות std::rc::Rc. ב-Go, אפשר לשתף ערכים על ידי אחסון מצביעים לערכים,
שמוסרים על ידי איסוף האשפה.
אבטחה
בידוד עומסי עבודה לפי פרויקט
בתשתית של Google, תוספים ששייכים לאותו Google Cloud פרויקט יכולים לפעול באותו ארגז חול מאובטח. כלומר, סביבת זמן הריצה של WebAssembly היא מחסום האבטחה היחיד בין תוספים באותו פרויקט.
כדאי להשתמש בפרויקטים נפרדים לעומסי עבודה שצריכים הפרדה לצורכי אבטחה. Google Cloud השיטה הזו גם מאפשרת הפרדה בין משאבים והרשאות.
הגבלת סודות ב-Media CDN
מבחינת העיצוב, Media CDN פועל על צי של חומרה שמופעל מחוץ לשליטה הפיזית של Google. כשכותבים תוספים שקשורים לאבטחה עבור Media CDN, צריך להשתמש בשמות מארחים או בתת-דומיינים ייעודיים, ולהגדיר תוספים עם מפתחות חתימה שמתחלפים לעיתים קרובות.