En esta página, se proporcionan sugerencias para escribir complementos de Service Extensions que sean correctos, tengan un buen rendimiento y estén bien aislados. La corrección es fundamental porque los complementos se ejecutan en un entorno de pruebas restringido del motor con una superficie de API limitada. El rendimiento es fundamental porque los complementos se ejecutan durante las solicitudes de los usuarios finales, con pequeñas cantidades de recursos. El aislamiento se proporciona a nivel del proyecto.
Cómo comenzar
Comienza con las muestras
Usa APIs compatibles
Ejecuta pruebas funcionales y comparativas
Comienza con las muestras
Una buena forma de comenzar es explorar nuestras muestras de código de complementos. Estos son ejemplos de patrones de complementos comunes, como el análisis de rutas o consultas, la reescritura de encabezados, el registro personalizado y la autenticación personalizada.
Usa las APIs compatibles
Los complementos deben compilarse en función de la interfaz binaria (ABI) de Proxy-Wasm. Las extensiones del servicio admiten un subconjunto de la ABI de Proxy-Wasm que incluye mutaciones de encabezado y cuerpo HTTP, respuestas locales, registro personalizado y configuración de complementos. Proxy-Wasm también admite un pequeño subconjunto de WASI Preview 1, incluidos stdout y stderr para el registro, clock_time_get y random_get.
Las extensiones de servicio no admiten temporizadores, métricas personalizadas, datos compartidos, colas compartidas ni llamadas de red salientes. Las extensiones de servicio tampoco admiten valores de devolución de devolución de llamada de complementos que intentan pausar el procesamiento de solicitudes y los ignoran.
Ejecuta pruebas funcionales y comparativas
Para evaluar la corrección y el rendimiento, proporcionamos una herramienta local de prueba de complementos que puede ejecutar, probar y comparar tu complemento. Invoca esta herramienta en un contenedor de Docker y pasa un archivo binario del complemento y un archivo .proto de texto de entradas y expectativas. Consulta la documentación del verificador local y el ejemplo de entrada de prueba.
Precisión
No confíes en los relojes
Considera los nombres de encabezado como si no distinguieran mayúsculas de minúsculas
No dependas de los relojes
Por motivos de seguridad, la hora del reloj se establece en la creación del contexto (para un complemento o una solicitud) y se mantiene congelada durante las invocaciones del complemento. Esto significa que los complementos de WebAssembly no deben suspenderse, ya que se agota el tiempo de espera porque no avanza el tiempo. También significa que los complementos no pueden medir su propio tiempo de ejecución, aunque esta información está disponible en Cloud Monitoring.
Trata los nombres de encabezado como si no distinguieran entre mayúsculas y minúsculas
Según la semántica HTTP, los nombres de los campos de encabezado HTTP deben tratarse como si no distinguieran entre mayúsculas y minúsculas. El uso de mayúsculas y minúsculas en los encabezados que escribe un complemento se puede cambiar antes de enviarlos a los clientes o backends.
Rendimiento
Evita fallas en los complementos
Compila para obtener velocidad de ejecución
Precompila expresiones regulares
Evita copiar datos en contextos HTTP
Evita las fallas de los complementos
Cuando un complemento falla, la solicitud que lo activó recibe un error. Si esto sucede con frecuencia, se limita la cantidad de reinicios del complemento, lo que genera ráfagas de errores que afectan a varios usuarios.
Para evitar fallas en el complemento, prueba lo siguiente:
- Evita las afirmaciones de todo tipo. En cambio, configura el registro de errores o las respuestas locales a los usuarios.
- En Rust, evita usar métodos, como
unwrap, que puedan generar pánicos. Además, puedes configurar el complemento para que controle las fallas conpanic::set_hook. - Prueba tu complemento con el probador de complementos que proporciona Google y asegúrate de que las entradas vacías o con formato incorrecto se controlen sin que el complemento falle.
Compila para obtener velocidad de ejecución
Compila tu código de WebAssembly para lograr la mejor velocidad de ejecución con la opción de compilación -O3 (para C++) o opt-level=3 (para Rust).
Compila previamente las expresiones regulares
Evita las operaciones que requieren mucha capacidad de procesamiento en la ruta por solicitud (en los controladores HTTP). En cambio, realiza cualquier trabajo que no sea específico de la solicitud durante la configuración del complemento y pasa cualquier estado precomputado a cada contexto de solicitud HTTP (también conocido como contexto de transmisión).
En particular, precompila las expresiones regulares durante la configuración del complemento. En nuestro ejemplo de código de regex, se muestra cómo lograrlo.
Evita copiar datos en contextos HTTP
Cuando compartas datos entre el contexto raíz y los contextos HTTP, evita las copias costosas o las llamadas a clon. En su lugar, comparte punteros o referencias. En C++, esto se puede hacer con std::shared_ptr o con punteros y referencias sin procesar, ya que el contexto raíz sobrevive a cualquier contexto HTTP. En Rust, los valores se pueden compartir con std::rc::Rc. En Go, los valores se pueden compartir almacenando punteros a los valores, que el recolector de basura quita.
Seguridad
Aísla las cargas de trabajo por proyecto
En la infraestructura de Google, los complementos que pertenecen al mismo proyecto Google Cloud pueden ejecutarse en el mismo entorno de pruebas seguro. Esto significa que el tiempo de ejecución de WebAssembly es la única barrera de seguridad entre los complementos del mismo proyecto.
Usa proyectos Google Cloud separados para las cargas de trabajo que necesiten separación de seguridad. Esta práctica también proporciona la separación de recursos y permisos.
Restringe los secretos en Media CDN
Por diseño, Media CDN se ejecuta en una flota de hardware que se opera fuera del control físico de Google. Cuando escribas complementos relacionados con la seguridad para Media CDN, usa nombres de host o subdominios dedicados, y configura los complementos con claves de firma que se rotan con frecuencia.