Struct GuardianDB 

pub struct GuardianDB { /* private fields */ }

Implementations

impl GuardianDB

pub async fn new( ipfs_config: Option<ClientConfig>, options: Option<NewGuardianDBOptions>, ) -> Result<Self>

Construtor de alto nível que configura o Keystore e a Identidade.

pub async fn new_guardian_db( ipfs: IpfsClient, identity: Identity, options: Option<NewGuardianDBOptions>, ) -> Result<Self>

Construtor principal para uma instância de GuardianDB.

pub fn tracer(&self) -> Arc<BoxedTracer>

Retorna o tracer para telemetria e monitoramento.

pub fn span(&self) -> &Span

Retorna uma referência ao span de tracing para instrumentação

pub fn ipfs(&self) -> &IpfsClient

Retorna o cliente da API do IPFS (Iroh nativo).

pub fn identity(&self) -> Identity

Retorna a identidade da instância do GuardianDB. A identidade é clonada para que o chamador possa usá-la sem manter o lock de leitura ativo.

pub fn peer_id(&self) -> PeerId

Retorna o PeerId da instância do GuardianDB. PeerId implementa o trait Copy, então o valor é copiado, o que é muito eficiente.

pub fn keystore(&self) -> Arc<RwLock<Option<Box<dyn Keystore + Send + Sync>>>>

Retorna um clone do Arc para o Keystore, permitindo o acesso compartilhado. O keystore é configurado durante a inicialização e pode ser usado para operações criptográficas.

pub fn close_keystore( &self, ) -> Option<Box<dyn Fn() -> Result<()> + Send + Sync>>

Retorna a função de fechamento para o Keystore, se existir.

Esta função retorna uma closure que pode ser chamada para fechar o keystore. A closure captura uma referência clonada para o campo close_keystore interno.

Retorna

• Some(closure) se uma função de fechamento foi configurada durante a inicialização
• None se nenhuma função de fechamento foi definida

Alternativa

Para uma interface mais simples, use close_key_store() diretamente.

pub fn set_store( &self, address: String, store: Arc<dyn Store<Error = GuardianError> + Send + Sync>, )

Adiciona ou atualiza uma store no mapa de stores gerenciadas. Esta operação adquire um lock de escrita.

pub fn delete_store(&self, address: &str)

Remove uma store do mapa de stores gerenciadas. Esta operação adquire um lock de escrita.

pub fn get_store( &self, address: &str, ) -> Option<Arc<dyn Store<Error = GuardianError> + Send + Sync>>

Busca uma store no mapa pelo seu endereço. Retorna Some(store) se encontrada, ou None caso contrário.

pub async fn close_all_stores(&self)

Itera sobre todas as stores gerenciadas e chama o método close() de cada uma. Clona a lista de stores para evitar manter o lock durante a chamada a close(), prevenindo possíveis deadlocks.

pub fn close_cache(&self)

Fecha o cache LevelDown, garantindo que todos os dados sejam persistidos e liberando os recursos associados.

pub async fn close_direct_connections(&self)

Fecha o canal de comunicação direta e registra um erro se a operação falhar.

pub fn close_key_store(&self)

Executa a função de fechamento do keystore, se ela tiver sido definida. Adquire um lock de escrita para garantir que a função não seja modificada enquanto é lida e executada.

pub fn get_access_controller_type( &self, controller_type: &str, ) -> Option<AccessControllerConstructor>

Busca um construtor de AccessController pelo seu tipo (nome). Retorna Some(constructor) se encontrado, ou None caso contrário.

pub fn access_controller_types_names(&self) -> Vec<String>

Retorna uma lista com os nomes de todos os tipos de AccessController registrados. Função auxiliar para debug e listagem de tipos disponíveis.

pub fn unregister_access_controller_type(&self, controller_type: &str)

Remove um construtor de AccessController do mapa pelo seu tipo. Esta operação adquire um lock de escrita.

pub fn register_access_controller_type_with_name( &self, controller_type: &str, constructor: AccessControllerConstructor, ) -> Result<()>

Registra um novo tipo de AccessController. A função construtora é executada uma vez para determinar o nome do tipo.

Executa o construtor para determinar o tipo dinâmico Registra um novo tipo de AccessController com tipo explícito.

pub async fn register_access_controller_type( &self, constructor: AccessControllerConstructor, ) -> Result<()>

Método legado mantido por compatibilidade - usa tipo padrão “simple”

pub fn register_store_type( &self, store_type: String, constructor: StoreConstructor, )

pub fn unregister_store_type(&self, store_type: &str)

Remove um construtor de Store do mapa pelo seu tipo.

pub fn store_types_names(&self) -> Vec<String>

Retorna uma lista com os nomes de todos os tipos de Store registrados.

pub fn get_store_constructor( &self, store_type: &str, ) -> Option<StoreConstructor>

Busca um construtor de Store pelo seu tipo (nome). Retorna Some(constructor) se encontrado, ou None caso contrário.

pub async fn close(&self) -> Result<()>

Encerra a instância do GuardianDB, fechando todas as stores, conexões e tarefas em background.

pub async fn create( &self, name: &str, store_type: &str, options: Option<CreateDBOptions>, ) -> Result<Arc<dyn Store<Error = GuardianError> + Send + Sync>>

Cria um novo banco de dados (store), determina seu endereço, salva localmente e o abre.

pub async fn open( &self, db_address: &str, options: CreateDBOptions, ) -> Result<Arc<dyn Store<Error = GuardianError> + Send + Sync>>

Abre um banco de dados a partir de um endereço GuardianDB.

pub async fn determine_address( &self, name: &str, store_type: &str, options: Option<DetermineAddressOptions>, ) -> Result<GuardianDBAddress>

Determina o endereço de um banco de dados criando seu manifesto e salvando no IPFS.

pub async fn load_cache( &self, directory: &Path, db_address: &GuardianDBAddress, ) -> Result<()>

Carrega o cache para um determinado endereço de banco de dados.

pub async fn have_local_data(&self, db_address: &GuardianDBAddress) -> bool

Verifica se o manifesto de um banco de dados existe no cache local.

pub async fn add_manifest_to_cache( &self, directory: &Path, db_address: &GuardianDBAddress, ) -> Result<()>

Adiciona o hash do manifesto de um banco de dados ao cache local.

pub async fn create_store( &self, store_type: &str, address: &GuardianDBAddress, options: CreateDBOptions, ) -> Result<Arc<dyn Store<Error = GuardianError> + Send + Sync>>

Lida com a lógica complexa de instanciar uma nova Store, incluindo a resolução do Access Controller, carregamento de cache e configuração de todas as opções.

pub async fn register_default_access_controller_types(&self) -> Result<()>

Registra os construtores padrão de access controllers disponíveis

pub fn register_default_store_types(&self)

Registra os construtores padrão de stores disponíveis

pub fn event_bus(&self) -> Arc<EventBusImpl>

Retorna o barramento de eventos da instância do GuardianDB.

pub async fn monitor_direct_channel( &self, event_bus: Arc<EventBusImpl>, ) -> Result<JoinHandle<()>>

Inicia uma tarefa em background para escutar eventos do pubsub e processá-los.

pub async fn handle_event_exchange_heads( &self, event: &MessageExchangeHeads, store: Arc<dyn Store<Error = GuardianError> + Send + Sync>, ) -> Result<()>

Processa um evento de troca de “heads”, sincronizando as novas entradas com a store local.

Realiza a sincronização completa dos heads recebidos, incluindo:

1. Validação de integridade dos heads
2. Verificação de permissões de acesso
3. Detecção de duplicatas existentes
4. Sincronização efetiva com a store
5. Emissão de eventos de progresso

Argumentos

• event - Evento contendo os heads a serem sincronizados e metadados
• store - Referência à store que receberá os heads

Processamento

1. Validação Básica: Verifica se os heads possuem dados válidos (hash, payload)
2. Controle de Acesso: Usa o access controller da store para validar permissões
3. Detecção de Duplicatas: Consulta o oplog para evitar reprocessamento
4. Sincronização: Delega para o método sync() da store que implementa a lógica completa
5. Eventos: Emite eventos de progresso para componentes interessados

Performance

• O(n) onde n = número de heads recebidos
• Paralelização: Validação sequencial, mas sync em batch para eficiência
• Cache-aware: Aproveita índices existentes para detecção de duplicatas

Erros

• Retorna erro se a sincronização da store falhar
• Heads individuais inválidos são ignorados (logged) mas não causam falha geral

Trait Implementations

impl BaseGuardianDB for GuardianDB

Implementação da trait BaseGuardianDB para GuardianDB

type Error = GuardianError

Define um tipo de erro associado para flexibilidade na implementação.

fn ipfs(&self) -> Arc<IpfsClient>

Retorna a instância da API do IPFS.

fn identity(&self) -> Arc<Identity>

Retorna a identidade utilizada pelo GuardianDB.

fn open<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, address: &'life1 str, options: &'life2 mut CreateDBOptions, ) -> Pin<Box<dyn Future<Output = Result<Arc<dyn Store<Error = GuardianError>>, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Cria ou abre uma store com o endereço e opções fornecidos.

fn get_store( &self, address: &str, ) -> Option<Arc<dyn Store<Error = GuardianError>>>

Retorna uma instância da store se ela já estiver aberta.

fn create<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, name: &'life1 str, store_type: &'life2 str, options: &'life3 mut CreateDBOptions, ) -> Pin<Box<dyn Future<Output = Result<Arc<dyn Store<Error = GuardianError>>, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Cria uma nova store com o nome, tipo e opções fornecidos.

fn determine_address<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, name: &'life1 str, store_type: &'life2 str, options: &'life3 DetermineAddressOptions, ) -> Pin<Box<dyn Future<Output = Result<Box<dyn Address>, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Determina o endereço de um banco de dados com base nos seus parâmetros.

fn register_store_type( &mut self, store_type: &str, constructor: StoreConstructor, )

Registra um novo tipo de Store.

fn unregister_store_type(&mut self, store_type: &str)

Desregistra um tipo de Store.

fn register_access_controller_type( &mut self, constructor: AccessControllerConstructor, ) -> Result<(), Self::Error>

Registra um novo tipo de Access Controller.

fn unregister_access_controller_type(&mut self, controller_type: &str)

Desregistra um tipo de Access Controller.

fn get_access_controller_type( &self, controller_type: &str, ) -> Option<AccessControllerConstructor>

Obtém um construtor de Access Controller pelo seu tipo.

fn event_bus(&self) -> EventBus

Retorna o barramento de eventos.

fn span(&self) -> &Span

Retorna o span para tracing.

fn tracer(&self) -> Arc<TracerWrapper>

Retorna o tracer para telemetria.

impl Drop for GuardianDB

Implementação do Drop trait para garantir cleanup seguro do GuardianDB

fn drop(&mut self)

Executes the destructor for this type.