Contexto de execução

O AppKit gerencia a autenticação do Databricks por meio de dois contextos:

ServiceContext (singleton): inicializado na inicialização do app com as credenciais do service principal
ExecutionContext: determinado em runtime — pode ser o contexto do service principal ou do usuário

Cabeçalhos de contexto do usuário

x-forwarded-user: obrigatório em produção; identifica o usuário
x-forwarded-access-token: obrigatório para o repasse do token do usuário

Usando `asUser(req)` para operações no escopo do usuário

O padrão asUser(req) permite que plugins executem operações com as credenciais do usuário que fez a requisição:

// Em um handler de rota de um plugin personalizado
router.post("/users/me/data", async (req, res) => {
  // Executa como o usuário (usa as permissions dele no Databricks)
  const result = await this.asUser(req).query("SELECT ...");
  res.json(result);
});

// Execução com o service principal (padrão)
router.post("/system/data", async (req, res) => {
  const result = await this.query("SELECT ...");
  res.json(result);
});

Funções auxiliares de contexto

Exportadas de @databricks/appkit:

getCurrentUserId(): retorna o ID do usuário no contexto de usuário; caso contrário, o ID do usuário de serviço
getWorkspaceClient(): retorna o WorkspaceClient adequado ao contexto atual
getWarehouseId(): Promise<string> (a partir de DATABRICKS_WAREHOUSE_ID ou selecionado automaticamente em desenvolvimento)
getWorkspaceId(): Promise<string> (a partir de DATABRICKS_WORKSPACE_ID ou obtido dinamicamente)

Atributos de span de telemetria

O span plugin.execute criado pela cadeia de interceptadores de execução inclui estes atributos:

Atributo	Tipo	Descrição
`execution.context`	`"user"`	`"service"`	Indica se a operação é executada como usuário (OBO) ou como service principal
`caller.id`	`string`	O ID do usuário (OBO) ou o ID do service principal
`execution.obo_dev_fallback`	`boolean`	Definido como `true` quando uma chamada OBO recorre ao service principal no modo de desenvolvimento

Esses atributos são adicionados automaticamente quando o seu plugin usa execute() ou executeStream(). Todos os plugins integrados usam esses métodos em suas operações OBO. Faça o mesmo em plugins personalizados para obter a instrumentação de telemetria automática.

Conexões por usuário no Lakebase

O plugin do Lakebase usa um mecanismo diferente para asUser(req): em vez de trocar o WorkspaceClient via AsyncLocalStorage, ele cria um pg.Pool separado para cada usuário, cada um com seu próprio refresh de OAuth token. Isso é necessário porque as conexões PostgreSQL são autenticadas no momento da conexão — o próprio pool é o limite de autenticação.

Consulte Plugin do Lakebase — conexões por usuário para mais detalhes.

Comportamento em modo de desenvolvimento

No desenvolvimento local (NODE_ENV=development), se asUser(req) for chamado sem um token de usuário, um aviso é registrado e a personificação do usuário é ignorada — em vez disso, a operação é executada com as credenciais padrão configuradas para o app. O span de telemetria mostrará execution.context: "service" com execution.obo_dev_fallback: true, para diferenciar esses casos das chamadas normais de service principal.