pt-br：5.8 file-system (#2310)

Section 5.8 file-system：
1. how-to-read-files-in-nodejs.md
2. how-to-search-files-and-directories-in-nodejs.md
3. how-to-store-local-config-data.md
4. how-to-use-the-path-module.md
5. how-to-write-files-in-nodejs.md
6. secutiry/introduction.md

Author: thalesbruno

locale/pt-br/knowledge/file-system/how-to-read-files-in-nodejs.md

@@ -0,0 +1,53 @@
+---
+title: Como eu leio arquivos no node.js?
+date: '2011-08-26T10:08:50.000Z'
+tags:
+  - filesystem
+difficulty: 2
+layout: knowledge-post.hbs
+---
+
+Ler o conteúdo de um arquivo na memória é uma tarefa muito comum na programação, e, como em muitas outras coisas, a API principal do Node.js fornece métodos para tornar isso trivial. Há uma variedade de métodos do sistema de arquivos, todos contidos no módulo `fs`.  O modo mais fácil de ler todo o conteúdo de um arquivo é com `fs.readFile`, como segue:
+
+    fs = require('fs');
+    fs.readFile(file, [encoding], [callback]);
+
+    // file = (string) caminho do arquivo a ser lido 
+
+`encoding` é um parâmetro opcional que especifica o tipo de codificação para ler o arquivo. As codificações possíveis são 'ascii', 'utf8' e 'base64'. Se nenhuma codificação for fornecida, o valor padrão é `null`.
+
+`callback` é uma função que será chamada quando um arquivo tiver sido lido e o conteúdo estiver pronto - são passados dois argumentos, `err` e `data`.  Se não houver erros, `err` será `null` e `data` conterá o conteúdo do arquivo; caso contrário `err` irá conter a mensagem de erro.
+
+Então, se nós quisermos ler o arquivo `/etc/hosts` e imprimí-lo no stdout (como o `cat` no UNIX):
+
+    fs = require('fs')
+    fs.readFile('/etc/hosts', 'utf8', function (err,data) {
+      if (err) {
+        return console.log(err);
+      }
+      console.log(data);
+    });
+
+O conteúdo do `/etc/hosts` deve estar visível para você agora, desde que você tenha permissão para ler o arquivo em primeiro lugar.
+
+Vamos agora dar uma olhada em um exemplo do que acontece quando você tenta ler um arquivo inválido - o exemplo mais fácil é um arquivo que não existe.
+
+    fs = require('fs');
+    fs.readFile('/doesnt/exist', 'utf8', function (err,data) {
+      if (err) {
+        return console.log(err);
+      }
+      console.log(data);
+    });
+
+Esta é a saída:
+
+    { stack: [Getter/Setter],
+      arguments: undefined,
+      type: undefined,
+      message: 'ENOENT, No such file or directory \'/doesnt/exist\'',
+      errno: 2,
+      code: 'ENOENT',
+      path: '/doesnt/exist' }
+
+Este é um [Error object](/what-is-the-error-object) básico do Node.js - muitas vezes pode ser útil logar diretamente `err.stack`, uma vez que ele contém uma stack trace para o local no código em que o objeto Error foi criado.

locale/pt-br/knowledge/file-system/how-to-search-files-and-directories-in-nodejs.md

@@ -0,0 +1,42 @@
+---
+title: Como eu procuro arquivos e diretórios?
+date: '2011-08-26T10:08:50.000Z'
+tags:
+  - filesystem
+difficulty: 1
+layout: knowledge-post.hbs
+---
+
+Suponha que você queira listar todos os arquivos no seu diretório atual.  Uma abordagem é utilizar a [função](/how-do-i-read-files-in-node-js) builtin `fs.readdir`. Isto lhe retornará um array com todos os arquivos e diretórios do caminho especificado:
+
+    fs = require('fs');
+
+    fs.readdir(process.cwd(), function (err, files) {
+      if (err) {
+        console.log(err);
+        return;
+      }
+      console.log(files);
+    });
+
+
+Infelizmente, se você quiser fazer uma lista recursiva dos arquivos, então as coisas rapidamente ficarão muito mais complicadas. Para evitar toda essa complexidade assustadora, esta é uma das circunstâncias onde uma biblioteca feita por usuários pode salvar o dia. [Node-findit](https://github.com/substack/node-findit), pela SubStack, é um módulo auxiliar para facilitar a busca por arquivos.  Ele tem interfaces para permitir você trabalhar com callbacks, eventos, ou simplesmente da velha forma síncrona (o que na maioria das vezes não é uma boa ideia).
+
+Para instalar `node-findit`, simplesmente use npm:
+
+    npm install findit
+
+Na mesma pasta, crie um arquivo chamado `example.js`, e então adicione este código.  Execute-o com `node example.js`.  Este exemplo usa o `node-findit` com a interface baseada em eventos.
+
+    //Isto instancia o localizador de arquivos
+    var finder = require('findit').find(__dirname);
+
+    //Isto fica escutando por diretórios encontrados
+    finder.on('directory', function (dir) {
+      console.log('Directory: ' + dir + '/');
+    });
+
+    //Isto fica escutando por arquivos encontrados
+    finder.on('file', function (file) {
+      console.log('File: ' + file);
+    });

locale/pt-br/knowledge/file-system/how-to-store-local-config-data.md

@@ -0,0 +1,85 @@
+---
+title: Como armazenar dados de configuração local
+date: '2011-08-26T10:08:50.000Z'
+tags:
+  - conventions
+  - filesystem
+difficulty: 1
+layout: knowledge-post.hbs
+---
+
+
+Armazenar os dados de configuração da sua aplicação Node.js é muito simples - cada objeto no JavaScript pode ser facilmente renderizado como [JSON](/what-is-json), que por sua vez é apenas dados em string que podem ser enviados ou salvos da maneira que você preferir.  A forma mais simples de fazer isso envolve os métodos built-in `JSON.parse()` e `JSON.stringify()`.
+
+Vamos dar uma olhada em um exemplo muito simples (e imaginário).  Primeiro, para salvar alguns dados bem simples:
+
+      var fs = require('fs');
+
+      var myOptions = {
+        name: 'Avian',
+        dessert: 'cake'
+        flavor: 'chocolate',
+        beverage: 'coffee'
+      };
+
+      var data = JSON.stringify(myOptions);
+
+      fs.writeFile('./config.json', data, function (err) {
+        if (err) {
+          console.log('There has been an error saving your configuration data.');
+          console.log(err.message);
+          return;
+        }
+        console.log('Configuration saved successfully.')
+      });
+
+É realmente simples - apenas `JSON.stringify()` e então salve-o do jeito que você quiser.
+
+Agora, vamos carregar alguns dados de configuração:
+
+      var fs = require('fs');
+
+      var data = fs.readFileSync('./config.json'),
+          myObj;
+
+      try {
+        myObj = JSON.parse(data);
+        console.dir(myObj);
+      }
+      catch (err) {
+        console.log('There has been an error parsing your JSON.')
+        console.log(err);
+      }
+
+NODE PRO TIP:  Mesmo que você não goste de usar `try/catch`, este é um lugar para usá-lo.  `JSON.parse` é um analisador JSON muito rígido, e erros são comuns - mais importante, contudo, `JSON.parse` usa a declaração `throw`  em vez de dar uma callback, então `try/catch` é o único jeito de se proteger contra os erros.
+
+Usar o método built-in `JSON` pode lhe levar longe, mas como tantos outros problemas que você pode estar procurando resolver com Node.js, já há uma solução da comunidade que pode levar você muito além.  A solução, neste caso, é o `nconf`.  Escrito por Charlie Robbins, é um gerenciador de configurações para Node.js que suporta armazenamento em memória, armazenamento de arquivos local, bem como suporte a backend `redis`, provido por um módulo separado.
+
+Vamos dar uma olhada agora em como nós realizaríamos acessos a algumas configurações locais com o `nconf`.  Primeiro, você precisará instalá-lo no diretório do projeto:
+
+      npm install nconf
+
+Após isso, a sintaxe é moleza. Veja um exemplo:
+
+      var nconf = require('nconf');
+
+      nconf.use('file', { file: './config.json' });
+      nconf.load();
+      nconf.set('name', 'Avian');
+      nconf.set('dessert:name', 'Ice Cream');
+      nconf.set('dessert:flavor', 'chocolate');
+
+      console.log(nconf.get('dessert'));
+
+      nconf.save(function (err) {
+        if (err) {
+          console.error(err.message);
+          return;
+        }
+        console.log('Configuration saved successfully.');
+      });
+
+A única coisa que requer atenção aqui é o delimitador - ':'. Quando se acessa propriedades aninhadas com o `nconf`, os dois-pontos são usados para delimitar os namespaces dos nomes das chaves.  Se uma sub-chave específica não é fornecida, o objeto inteiro é definido ou retornado.
+
+Quando usa-se o `nconf` para guardar seus dados de configurações em um arquivo, `nconf.save()` e `nconf.load()` são os únicos momentos em que acontecerá interações com o arquivo atual.  Todos os outros acessos são realizados em uma cópia de seus dados em memória, que não serão persistidos sem uma chamada do `nconf.save()`.  De maneira semelhante, se você está tentando trazer de volta dados de configuração da última vez que sua aplicação rodou, eles não existirão em memória sem uma chamada para `nconf.load()`, como mostrado acima.
+

locale/pt-br/knowledge/file-system/how-to-use-the-path-module.md

@@ -0,0 +1,68 @@
+---
+title: Como usar o módulo path?
+date: '2011-08-26T10:08:50.000Z'
+tags:
+  - core
+  - filesystem
+difficulty: 1
+layout: knowledge-post.hbs
+---
+
+O módulo path contém muitas funções auxiliares para ajudar a tornar a manipulação de caminhos mais fácil.
+
+A primeira função que vale a pena mencionar é `path.normalize`.  Esta função pega um caminho (na forma de uma string) e remove  barras duplicadas e normaliza abreviações de diretórios, como '.' para 'este diretório' e '..' para 'um diretório acima'. Por exemplo:
+
+    > var path = require('path');
+    > path.normalize('/a/.///b/d/../c/')
+    '/a/b/c/'
+
+Uma função  intimamente relacionada a `normalize` é `join`.  Esta função recebe um número variável de argumentos, junta-os, e normaliza o caminho.
+
+    > var path = require('path');
+    > path.join('/a/.', './//b/', 'd/../c/')
+    '/a/b/c'
+
+Um uso possível do `join` é para manipular caminhos quando servem urls:
+
+    > var path = require('path');
+    > var url = '/index.html';
+    > path.join(process.cwd(), 'static', url);
+    '/home/nico/static/index.html'
+
+Há três funções que são usadas para extrair as várias partes do nome de um caminho: `basename`, `extname`, e `dirname`. 
+- `basename` retorna o último pedaço do caminho recebido. 
+- `extname` retorna a extensão do último pedaço. Geralmente para diretórios, `extname` retorna apenas ''. 
+- Finalmente, `dirname` retorna tudo que `basename` não retorna.
+Por exemplo:
+
+    > var path = require('path')
+    > var a = '/a/b/c.html'
+    > path.basename(a)
+    'c.html'
+    > path.extname(a)
+    '.html'
+    > path.dirname(a)
+    '/a/b'
+
+Note que `basename` tem um segundo parâmetro opcional que extrairá a extensão se você passa a extensão correta.
+
+    > var path = require('path')
+    > var a = '/a/b/c.html'
+    > path.basename(a, path.extname(a))
+    'c'
+
+Por último, o módulo `path` fornece métodos para checar se um determinado caminho existe ou não: `exists` e `existsSync` Os dois recebem o caminho de um arquivo como primeiro parâmetro. 
+
+`exists` recebe uma callback como seu segundo parâmetro, a qual é retornado um booleano representando a existência do arquivo. 
+
+`existsSync`, por outro lado, checa o caminho recebido de forma síncrona.  No Node.js, você normalmente irá querer usar as funções assíncronas para entrada/saída no sistema de arquivos - as versões síncronas bloquearão todo o seu processo até que esteja finalizado. 
+
+Bloqueio nem sempre é uma coisa ruim.  Checar a existência de um arquivo de configuração essencial de forma síncrona faz sentido, por exemplo - não interessa muito se seu processo está bloqueado por algo que ele não pode viver sem!  Por outro lado, entretanto, em um servidor HTTP muito ativo, qualquer entrada/saída de arquivos por requisição **DEVE** ser assíncrona, senão você responderá as requisições uma por uma. Veja o artigo em [operações assíncronas](/how-to-write-asynchronous-code) para mais detalhes.
+
+        > var path = require('path')
+        > path.exists('/etc', function(exists){console.log("Does the file exist?", exists)})
+        > Does the file exist? true
+
+        > path.existsSync('/etc')
+        true
+

locale/pt-br/knowledge/file-system/how-to-write-files-in-nodejs.md

@@ -0,0 +1,50 @@
+---
+title: Como eu escrevo arquivos no node.js?
+date: '2011-08-26T10:08:50.000Z'
+tags:
+  - filesystem
+difficulty: 2
+layout: knowledge-post.hbs
+---
+
+Escrever em um arquivo é outra das tarefas básicas da programação que um desenvolvedor normalmente precisa conhecer - por sorte, esta tarefa é muito simples no Node.js.  Nós podemos usar o conveniente método `writeFile` do módulo `fs` da biblioteca padrão, que pode evitar todo tipo de problemas e economizar tempo.
+
+    fs = require('fs');
+    fs.writeFile(filename, data, [encoding], [callback])
+
+`file = (string)` caminho do arquivo a ser lido
+
+`data = (string or buffer)` os dados que você quer escrever no arquivo
+
+`encoding = (optional string)` a codificação de `data`. Codificações possíveis são 'ascii', 'utf8', e 'base64'. Se nenhuma codificação for passada, então a 'utf8' será assumida.
+
+`callback = (optional function (err) {})` Se não houver erro, `err === null`, se houver, `err` conterá a mensagem de erro.
+
+Então, se nós quisermos escrever "Hello World" em `helloworld.txt`:
+
+    fs = require('fs');
+    fs.writeFile('helloworld.txt', 'Hello World!', function (err) {
+      if (err) return console.log(err);
+      console.log('Hello World > helloworld.txt');
+    });
+
+    [conteúdo de helloworld.txt]:
+    Hello World!
+
+Se nós propositalmente quisermos causar um erro, podemos tentar escrever em um arquivo que nós não temos permissão de acesso:
+
+    fs = require('fs')
+    fs.writeFile('/etc/doesntexist', 'abc', function (err,data) {
+      if (err) {
+        return console.log(err);
+      }
+      console.log(data);
+    });
+
+    { stack: [Getter/Setter],
+      arguments: undefined,
+      type: undefined,
+      message: 'EACCES, Permission denied \'/etc/doesntexist\'',
+      errno: 13,
+      code: 'EACCES',
+      path: '/etc/doesntexist' }

locale/pt-br/knowledge/file-system/security/introduction.md

@@ -0,0 +1,50 @@
+---
+title: Como eu posso proteger meu código?
+date: null
+tags:
+  - filesystem
+  - security
+difficulty: 3
+layout: knowledge-post.hbs
+---
+
+Às vezes, você pode querer deixar usuários lerem ou escreverem arquivos em seu servidor. Por exemplo, talvez você queira escrever um software de fórum sem usar um banco de dados de verdade. O problema é que você não quer que seus usuários possam modificar ou ler todo e qualquer arquivo em seu servidor, e por vezes há formas de contornar restrições que deveriam impedi-los. Continue lendo para ver como você pode proteger seu código contra atacantes malvados tentando bagunçar seus arquivos.
+
+Poison Null Bytes
+=================
+Poison null bytes é um modo de enganar o seu código para que ele veja outro nome de arquivo em vez do que realmente está sendo aberto. Isto pode, em muitos casos, ser usado para contornar proteções a directory traversal, para enganar servidores a entregar arquivos com tipos errados e para contornar restrições nos nomes de arquivos que podem ser usados. [Aqui está uma descrição mais detalhada.](http://groups.google.com/group/nodejs/browse_thread/thread/51f66075e249d767/85f647474b564fde) Sempre use código como este quando estiver acessando arquivos com nomes fornecidos pelo usuário:
+
+    if (filename.indexOf('\0') !== -1) {
+      return respond('That was evil.');
+    }
+
+Whitelisting
+============
+Você nem sempre será capaz de usar whitelisting, mas se for, é muito fácil de implementar e difícil de dar errado. Por exemplo, se você souber que todos os nomes de arquivos são strings alfanuméricas em caixa baixa:
+
+    if (!/^[a-z0-9]+$/.test(filename)) {
+      return respond('illegal character');
+    }
+
+Contudo, note que whitelisting sozinha não será suficiente assim que você permitir pontos e barras - pessoas poderiam entrar com coisas como `../../etc/passwd` a fim de obter arquivos de fora da pasta permitida.
+
+Prevenindo Directory Traversal
+==============================
+Directory traversal significa que um atacante tenta acessar arquivos fora do diretório que você quer permitir que ele acesse. Você pode prevenir isto usando o módulo "path" nativo do Node.js. **Não reimplementar as coisas no módulo path por conta própria** - por exemplo, quando alguém executa seu código em um servidor windows, não manipular barras invertidas como barras normais permitirá que atacantes façam directory traversal.
+
+Este exemplo assume que você já checou a variável `userSuppliedFilename`  como descrito na seção acima "Poison Null Bytes".
+
+    var rootDirectory = '/var/www/';
+
+Garanta que você tem uma barra no final do nome dos diretórios permitidos - você não quer que pessoas sejam capazes de acessar `/var/www-secret/`, não é?.
+
+    var path = require('path');
+    var filename = path.join(rootDirectory, userSuppliedFilename);
+
+Agora `filename` contém um caminho absoluto e não contém mais sequências `..` - `path.join` cuida disso. Entretanto, pode ser algo como `/etc/passwd` agora, aí você tem que checar se começa com `rootDirectory`:
+
+    if (filename.indexOf(rootDirectory) !== 0) {
+      return respond('trying to sneak out of the web root?');
+    }
+
+Agora a varável `filename` deve conter o nome do arquivo ou  diretório que está dentro do diretório permitido (a menos que ele não exista).