Nosso Comunidade Postagem de convidado vem de Joel Andrews. Joel é um desenvolvedor poliglota que vive na chuvosa costa oeste do Canadá. Ele desempenha várias funções na Kashoo, incluindo desenvolvedor de back-end, administrador de banco de dados, desenvolvedor de DevOps, proprietário de produto e, ocasionalmente, desenvolvedor de front-end para Web e Android. Ele tem um amor profundo e permanente por Couchbase (especialmente Couchbase Mobile), o que o torna completamente imparcial ao discutir os prós e os contras de qualquer solução de armazenamento de dados.
Ao criar qualquer sistema com componentes de cliente e servidor, é fundamental validar os dados que o cliente tenta armazenar no servidor e garantir que somente as pessoas autorizadas possam visualizá-los ou modificá-los. Caso contrário, um cliente mal-intencionado pode se aproveitar do seu sistema para fazer todo tipo de coisa desagradável. É por isso que, quando nós da Kashoo começamos a usar o Couchbase Mobile e o Sync Gateway para sincronizar dados entre vários dispositivos móveis e nosso aplicativo da Web, criamos nossas funções de sincronização para executar uma validação abrangente de todas as propriedades do documento e as permissões (ou seja, canais) que seriam necessárias para ler, criar, substituir e excluir.
A flexibilidade do API da função de sincronização do Sync Gateway pode ser tanto uma bênção quanto uma maldição. Descobrimos que, ao começar com um bucket simples que tinha apenas alguns tipos de documentos, não era muito difícil manter as coisas organizadas e passíveis de manutenção e, ao mesmo tempo, realizar uma boa quantidade de validação. No entanto, à medida que adicionávamos mais e mais tipos de documentos, o tamanho e a complexidade da nossa função de sincronização rapidamente saíram do controle. Escrever uma função de sincronização que execute uma validação abrangente torna-se cada vez mais incontrolável quanto mais tipos de documentos você adicionar... isto é, a menos que você comece a aplicar alguma estrutura ao código.
Isso nos levou a dividir a função de sincronização do nosso banco de dados Sync Gateway em quatro fases principais:
-
Descubra o tipo de documento
-
Verifique se o usuário pertence a um dos canais necessários para realizar a operação
-
Validar cada uma das propriedades do documento
-
Atribuir canais ao documento
Isso funcionou bem até introduzirmos um segundo banco de dados Sync Gateway. Como as funções de sincronização são definidas como um único bloco de código sem a capacidade de carregar dinamicamente bibliotecas externas, duplicamos a estrutura aproximada que havíamos criado para a função de sincronização do primeiro banco de dados na função de sincronização do segundo banco de dados. No entanto, como desenvolvedores, essa duplicação de código não nos agradou muito, pois significava que, à medida que fizéssemos melhorias em uma função de sincronização, teríamos que portar manualmente essas alterações para a outra ou elas se distanciariam gradualmente uma da outra em termos de funcionalidade.
Assim, decidimos evoluir ainda mais a estrutura aproximada para uma ferramenta autônoma que pode ser compartilhada entre bancos de dados do Sync Gateway sem exigir duplicação de código. Como a API da função de sincronização do Sync Gateway não permite o uso de bibliotecas externas, adotamos a abordagem de geração de código em vez de vinculação dinâmica: você escreve as definições do tipo de documento como objetos JavaScript e, em seguida, usa o utilitário para importar essas definições em um modelo pré-gerado para criar uma função de sincronização coesa e independente.
Agora, tínhamos uma maneira de definir nossos tipos de documentos (ou "esquema") de uma forma muito declarativa, mais próxima de escrever uma configuração do que de escrever um código, e onde as definições de tipos de documentos podem ser mantidas de forma totalmente independente do código que realmente executa a autorização, a validação e a atribuição de canais. Isso eliminou grande parte da duplicação de código que era necessária anteriormente. E funcionou muito bem para nós. Funcionou tão bem, de fato, que decidimos liberação e apoiar o utilitário como software de código aberto para que outros não precisem duplicar nossos esforços. O utilitário chama-se synctos e já está disponível para uso sob a licença MIT altamente permissiva.
Desde seu lançamento inicial, também expandimos seus recursos, de modo que agora ele executa cinco fases, em vez das quatro originais, e cada fase é significativamente mais robusta:
-
Descubra o tipo de documento
-
Autorizar o usuário, determinando se
-
o usuário pertence a um dos canais necessários para realizar a operação
-
o usuário pertence a uma das funções necessárias para executar a operação
-
o usuário recebeu explicitamente permissão para realizar a operação
-
-
Validar cada uma das propriedades do documento
-
Atribuir acesso:
-
adicionar usuários e/ou funções aos canais
-
adicionar usuários a funções
-
-
Atribuir canais ao documento
Aqui está um exemplo de definição de tipo de documento para lhe dar uma ideia do que o synctos é capaz de fazer:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
{ // Uma solicitação/requisição de pagamento de uma fatura paymentRequisition: { // Determinar se o documento é desse tipo typeFilter: função(doc, oldDoc) { retorno doc.tipo === 'paymentRequisition' || oldDoc.tipo === 'paymentRequisition'; }, // Os canais aos quais o documento será atribuído. // Para que um usuário possa realizar cada operação, ele deve pertencer a pelo menos um dos canais listados para esse tipo de operação. canais: { adicionar: [ 'create-payment-requisition' (criar requisição de pagamento) ], substituir: [ 'replace-payment-requisition' ], remover: [ 'remove-payment-requisition' (remover requisição de pagamento) ] }, // Definir o que é esperado de cada uma das propriedades que pertencem a esse tipo de documento validadores de propriedade: { tipo: { // O tipo do documento tipo: 'string', necessário: verdadeiro, imutável: verdadeiro }, businessId: { // O ID da empresa à qual a requisição de pagamento está associada tipo: 'integer', necessário: verdadeiro, imutável: verdadeiro, ValorMínimo: 1 }, invoiceRecordId: { // O ID da fatura à qual a requisição de pagamento está associada tipo: 'integer', necessário: verdadeiro, imutável: verdadeiro, ValorMínimo: 1 }, issuedAt: { // Quando a requisição de pagamento foi enviada/emitida tipo: 'datetime', imutável: verdadeiro }, issuedByUserId: { // O ID do usuário que emitiu a requisição de pagamento tipo: 'string', imutável: verdadeiro, mustNotBeEmpty: verdadeiro }, destinatários da fatura: { // Quem recebeu a requisição de pagamento tipo: 'string' } } } } |
É fácil começar a usar o synctos usando npm (o gerenciador de pacotes para o Node.js). Execute o seguinte em um diretório vazio:
|
1 |
npm instalar síncronos |
Isso fará o download da versão mais recente do synctos para o diretório local node_modules. E, agora que o synctos foi baixado, se você salvar o exemplo de definições de documentos acima em um arquivo chamado "example-doc-definitions.js", poderá usar o synctos para gerar uma função de sincronização a partir dele:
node_modules/synctos/make-sync-function ./example-doc-definitions.js ./example-generated-sync-function.js
Isso deve ter criado uma função de sincronização totalmente autônoma, combinando o modelo predefinido do synctos com as definições de documento que você forneceu, como você verá se abrir "example-generated-sync-function.js" em um editor de texto. A função de sincronização gerada pode então ser inserida literalmente em um arquivo de configuração do Sync Gateway.
Veja a seguir um exemplo simples de configuração do Sync Gateway que usa uma instância na memória do Morsa para que você possa experimentar a função de sincronização sem precisar configurar um bucket do Couchbase Server. Substitua a string "%GENERATED_SYNC_FUNCTION%" com a função de sincronização que foi gerada na etapa anterior. Observe que os pontos e aspas (`) que cercam a função de sincronização são uma adição personalizada ao formato JSON que permite cadeias de caracteres de várias linhas em um Sync Gateway arquivo de configuração.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "bancos de dados": { "synctos-test": { "servidor": "walrus:", "usuários": { "meu-usuário": { "admin_channels": [ "create-payment-requisition" (criar requisição de pagamento), "replace-payment-requisition" ], "senha": "senha" } }, "sync": `%FUNÇÃO_GERADA_SINCRONIZADA%` } } } |
Salve a configuração do Sync Gateway acima como "example-sync-gateway-config.json" e, em seguida, inicie o Sync Gateway com a nova configuração:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
/caminho/para/sincronização_portal ./exemplo-sincronização-portal-configuração.json Agora uso a ferramenta como enrolar para criar a novo instância de o "paymentRequisition" (requisição de pagamento) documento tipo. Para exemplo: enrolar -X PUT -u "my-user:password" -H "Content-Type: application/json" -d '{ "type": "paymentRequisition", "businessId": 15, "invoiceRecordId": 79, "issuedAt": "2017-01-11T18:21:18-0800", "issuedByUserId": "my-user", "invoiceRecipients": "foo@example.com,bar@example.com" }' "http://localhost:4984/synctos-test/myDoc1" O resposta vontade indicar sucesso: {"id":"myDoc1","ok":verdadeiro,"rev":"1-ed7b6831f4339188eee412082d44ca32"} |
Criar um documento válido é ótimo, mas o que acontece se tentarmos substituir esse documento por outro que viole a definição do documento? Observe que, no exemplo a seguir, o valor da propriedade "businessId" foi modificado de seu valor original de 15; isso é um problema porque a propriedade foi marcada como "imutável" na definição do documento.
|
1 2 3 4 5 6 7 8 |
enrolar -X PUT -u "my-user:password" -H "Content-Type: application/json" -d '{ "type": "paymentRequisition", "businessId": 99999, "invoiceRecordId": 79, "issuedAt": "2017-01-11T18:21:18-0800", "issuedByUserId": "my-user", "invoiceRecipients": "new-email@example.com" }' "http://localhost:4984/synctos-test/myDoc1?rev=1-ed7b6831f4339188eee412082d44ca32" |
A resposta será um erro:
|
1 |
{"error" (erro):"Proibido","razão":"Documento paymentRequisition inválido: valor do item "businessId" não pode ser modificado"} |
Como você pode ver, o synctos gera mensagens de erro detalhadas que facilitam a determinação do que deu errado ao tentar escrever uma revisão de documento. Este é um exemplo simples com apenas um erro de validação, mas se o documento contivesse vários erros, cada erro adicional seria enumerado na mensagem de erro da resposta.
E se tentarmos executar uma operação que exija um canal ao qual nosso usuário não pertence? Lembre-se de que o usuário que definimos na configuração do Sync Gateway não pertence ao canal "remove-payment-requisition", portanto não deve ter permissão para remover o documento que criamos anteriormente.
|
1 2 3 |
enrolar -X DELETE -u "my-user:password" "http://localhost:4984/synctos-test/myDoc1?rev=1-ed7b6831f4339188eee412082d44ca32" E de fato o resposta indica que o usuário faz não pertencer para o necessário canal: {"error" (erro):"Proibido","razão":"acesso ao canal ausente"} |
Há muito mais no synctos (por exemplo, atribuir acesso a usuários e funções, executar ações personalizadas após cada fase da função de sincronização e validar as funções de sincronização geradas usando o módulo de teste integrado), mas esperamos que isso tenha lhe dado uma ideia do que ele é capaz de fazer e de como pode ajudá-lo a escrever funções de sincronização do Sync Gateway que validem seus documentos de forma abrangente. Consulte a documentação do projeto em GitHub ou npm para obter muito mais detalhes.
