Documentation
¶
Overview ¶
Copyright 2025 Raywall Malheiros de Souza Licensed under the Mozilla Public License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.mozilla.org/en-US/MPL/2.0/
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Package api fornece um framework para orquestrar chamadas de API externas em um pipeline concorrente, respeitando dependências, e utilitários para obtenção de tokens de segurança (STS).
Visão Geral: O pacote `api` foi projetado para gerenciar a complexidade de sistemas que precisam chamar múltiplas APIs de terceiros ou microserviços internos. Ele utiliza a estrutura APIPipeline para executar essas chamadas em paralelo e garante que nenhuma API seja executada antes que todas as suas dependências tenham retornado um resultado. Ele também inclui um serviço de Token (STS) para gerenciar a autenticação nessas APIs.
Funcionalidades Principais:
- APIPipeline: Execução concorrente de múltiplas chamadas HTTP com gerenciamento de dependências, usando a lógica de um grafo dirigido acíclico (DAG).
- Circuit Breaker: APIs marcadas como Required cancelam todo o pipeline (erros 422) se falharem.
- TokenService: Simplifica a obtenção e gerenciamento de tokens de acesso (STS).
Exemplos de Uso:
Exemplo Básico de Pipeline: Demonstra como configurar e executar um pipeline de APIs.
configA := api.APIConfig{Name: "User", Host: "https://user-api/v1/user", HttpMethod: "GET"}
configB := api.APIConfig{
Name: "Profile",
Dependencies: []string{"User"}, // Depende de 'User'
Host: "https://profile-api/v1/profile",
HttpMethod: "POST",
}
pipeline := api.NewAPIPipeline([]api.APIConfig{configA, configB})
results, err := pipeline.Execute(context.Background(), nil)
if err != nil {
// Tratar erro do pipeline
}
fmt.Printf("Dados do User: %v\n", results["User"])
Exemplo de Token Service: Demonstra como obter um token usando a configuração STS.
ts := api.NewTokenService()
ts.Configurations["my_auth"] = api.TokenConfig{...} // Configuração real
token, err := ts.GetToken("my_auth")
if err != nil {
// Tratar erro
}
fmt.Println("Token Obtido:", *token)
Configuração: O pipeline é configurado com um slice de `APIConfig`. O TokenService é configurado alimentando o mapa `Configurations`.
Copyright 2025 Raywall Malheiros de Souza Licensed under the Mozilla Public License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.mozilla.org/en-US/MPL/2.0/
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Copyright 2025 Raywall Malheiros de Souza Licensed under the Mozilla Public License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.mozilla.org/en-US/MPL/2.0/
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound é retornado quando um recurso (configuração de token) não é encontrado. ErrNotFound = errors.New("not found") // ErrBadRequest é retornado para erros de requisição inválida. ErrBadRequest = errors.New("bad request") )
Functions ¶
This section is empty.
Types ¶
type APIConfig ¶
type APIConfig struct {
// Name é o identificador único da API no pipeline.
Name string
// Required, se true, qualquer falha desta API cancela todo o pipeline
// e retorna um erro 422 (circuit break).
Required bool
// Dependencies lista os nomes das APIs (APIConfig.Name) das quais esta API depende.
Dependencies []string
// Parameters contém os detalhes de como a chamada HTTP será montada.
Parameters APIParameters
}
APIConfig define a configuração necessária para uma chamada de API.
É o bloco de construção fundamental do pipeline, especificando como e quando uma API deve ser chamada.
type APIParameters ¶
type APIParameters struct {
// AccessToken é o token de autenticação (se aplicável).
AccessToken *string
// HttpMethod é o método HTTP (GET, POST, PUT, etc.).
HttpMethod string
// Host é a URL completa para a chamada da API.
Host string
// Body é o corpo da requisição, serializado para JSON.
Body map[string]interface{}
// Headers são os cabeçalhos HTTP adicionais para a requisição.
Headers map[string]string
}
APIParameters define os parâmetros e argumentos para a chamada da API.
type APIPipeline ¶
type APIPipeline struct {
// contains filtered or unexported fields
}
APIPipeline gerencia a execução paralela de APIs com dependências.
Ele coordena o fluxo de execução, coleta resultados e trata erros de forma concorrente.
func (*APIPipeline) Execute ¶
func (p *APIPipeline) Execute(ctx context.Context, input interface{}) (map[string]interface{}, error)
Execute executa todas as APIs respeitando dependências e concorrência.
O método gerencia a lógica de agendamento (iniciar APIs sem dependências e, em seguida, iniciar APIs dependentes à medida que os resultados são coletados).
Parâmetros:
ctx: Contexto para controle de timeout ou cancelamento. input: Payload de entrada (atualmente não usado na lógica de dependência).
Retorna:
map[string]interface{}: Um mapa onde a chave é o nome da API e o valor
é a resposta HTTP decodificada.
error: Retorna um erro se o contexto for cancelado ou se uma API
obrigatória (`Required`) falhar (erro 422).
Erros:
- "contexto cancelado": Quando o `ctx.Done()` é disparado.
- "erro 422: API obrigatória '%s' falhou": Se `APIConfig.Required` for true e a chamada falhar.
type APIPipelineInterface ¶
type APIPipelineInterface interface {
// Execute inicia a execução do pipeline de APIs.
Execute(ctx context.Context, input interface{}) (map[string]interface{}, error)
}
APIPipelineInterface realiza a abstração da estrutura APIPipeline.
Esta interface define o contrato mínimo para a execução do pipeline.
func NewAPIPipeline ¶
func NewAPIPipeline(apis []APIConfig) APIPipelineInterface
NewAPIPipeline cria uma nova instância do APIPipeline.
Parâmetros:
apis: O slice de APIConfig que define todo o fluxo do pipeline.
Retorna:
APIPipelineInterface: A instância configurada do pipeline, pronta para ser executada.
Exemplo:
p := NewAPIPipeline([]APIConfig{...})
type APIResult ¶
type APIResult struct {
// Name é o nome da API que retornou o resultado.
Name string
// Data contém o corpo da resposta HTTP (JSON decodificado).
Data interface{}
// Error contém o erro da chamada, se houver.
Error error
}
APIResult encapsula o resultado de uma chamada de API, seja sucesso ou falha.
type TokenConfig ¶
type TokenConfig struct {
// GrantType é o tipo de concessão de token (ex: "client_credentials").
GrantType string
// ClientID é o ID do cliente registrado no STS.
ClientID string
// ClientSecret é o segredo do cliente para autenticação.
ClientSecret string
// Host é a URL do endpoint de token.
Host string
// HttpMethod é o método HTTP (geralmente POST) para a requisição de token.
HttpMethod string
}
TokenConfig define a configuração necessária para interagir com um serviço STS (Security Token Service, como OAuth2/OpenID Connect).
type TokenService ¶
type TokenService struct {
// Configurations armazena as configurações de diferentes serviços STS por ID.
Configurations map[string]TokenConfig
// contains filtered or unexported fields
}
TokenService define os serviços para geração e gerenciamento de tokens STS.
É o principal ponto de interação para autenticação em APIs externas.
func NewTokenService ¶
func NewTokenService() *TokenService
NewTokenService cria uma nova instância do TokenService.
Retorna:
*TokenService: A instância inicializada.
Exemplo:
ts := NewTokenService()
func (*TokenService) GetToken ¶
func (t *TokenService) GetToken(tokenId string) (*string, error)
GetToken realiza uma requisição ao serviço STS para obter um token de acesso.
A requisição é montada com os dados application/x-www-form-urlencoded a partir da TokenConfig associada ao `tokenId`.
Parâmetros:
tokenId: O identificador da configuração de token a ser usada.
Retorna:
*string: O token de acesso (access_token) como um ponteiro para string, se obtido. error: Um erro se a configuração não for encontrada ou a requisição falhar.
Exemplo:
token, err := ts.GetToken("api_oauth")
Erros:
- ErrNotFound: Se o `tokenId` não estiver presente em `Configurations`.
- Erros de rede ou I/O.
- Erros de decodificação JSON ou falha ao encontrar "access_token" na resposta.
Source Files