Contexto de ejecución

AppKit gestiona la autenticación de Databricks mediante dos contextos:

• ServiceContext (singleton): se inicializa al arrancar la app con las credenciales del service principal
• ExecutionContext: se determina en runtime, ya sea como service principal o como contexto de usuario

Encabezados para el contexto de usuario

• x-forwarded-user: obligatorio en producción; identifica al usuario
• x-forwarded-access-token: obligatorio para la propagación del token de usuario

Uso de asUser(req) para operaciones con alcance de usuario

El patrón asUser(req) permite que los plugins ejecuten operaciones con las credenciales del usuario que realiza la solicitud:

// En un handler de ruta de un plugin personalizado
router.post("/users/me/data", async (req, res) => {
  // Ejecutar como el usuario (usa sus permisos de Databricks)
  const result = await this.asUser(req).query("SELECT ...");
  res.json(result);
});

// Ejecución como service principal (por defecto)
router.post("/system/data", async (req, res) => {
  const result = await this.query("SELECT ...");
  res.json(result);
});

Funciones auxiliares de contexto

Exportadas desde @databricks/appkit:

• getCurrentUserId(): devuelve el ID del usuario en el contexto de usuario; en caso contrario, el ID del usuario de servicio
• getWorkspaceClient(): devuelve el WorkspaceClient adecuado para el contexto actual
• getWarehouseId(): Promise<string> (a partir de DATABRICKS_WAREHOUSE_ID o seleccionado automáticamente en desarrollo)
• getWorkspaceId(): Promise<string> (a partir de DATABRICKS_WORKSPACE_ID u obtenido dinámicamente)

Atributos de span de telemetría

El span plugin.execute que crea la cadena de interceptores de ejecución incluye estos atributos:

Estos atributos se añaden automáticamente cuando tu plugin usa execute() o executeStream(). Todos los plugins integrados usan estos métodos para sus operaciones OBO. Los plugins personalizados deberían hacer lo mismo para obtener instrumentación de telemetría automática.

Conexiones por usuario en Lakebase

El plugin de Lakebase usa un mecanismo distinto para asUser(req): en lugar de intercambiar el WorkspaceClient mediante AsyncLocalStorage, crea un pg.Pool independiente por usuario, cada uno con su propia renovación del token OAuth. Esto es necesario porque las conexiones de PostgreSQL se autentican en el momento de establecerse: el propio pool es el límite de autenticación.

Consulta Plugin de Lakebase: conexiones por usuario para más detalles.

Comportamiento en modo de desarrollo

En desarrollo local (NODE_ENV=development), si se llama a asUser(req) sin un token de usuario, se registra una advertencia y se omite la suplantación del usuario: en su lugar, la operación se ejecuta con las credenciales predeterminadas configuradas para la aplicación. El span de telemetría mostrará execution.context: "service" junto con execution.obo_dev_fallback: true, lo que permite distinguir estos casos de las llamadas habituales del service principal.