+ | Flag | Meaning |
|---|
+
+ | --inspect |
+
+
+ - Enable inspector agent
+ - Listen on default address and port (127.0.0.1:9229)
+
+ |
+
+
+ | --inspect=[host:port] |
+
+
+ - Enable inspector agent
+ - Bind to address or hostname host (default: 127.0.0.1)
+ - Listen on port port (default: 9229)
+
+ |
+
+
+ | --inspect-brk |
+
+
+ - Enable inspector agent
+ - Listen on default address and port (127.0.0.1:9229)
+ - Break before user code starts
+
+ |
+
+
+ | --inspect-brk=[host:port] |
+
+
+ - Enable inspector agent
+ - Bind to address or hostname host (default: 127.0.0.1)
+ - Listen on port port (default: 9229)
+ - Break before user code starts
+
+ |
+
+
+ node inspect script.js |
+
+
+ - Spawn child process to run user's script under --inspect flag;
+ and use main process to run CLI debugger.
+
+ |
+
+
+ node inspect --port=xxxx script.js |
+
+
+ - Spawn child process to run user's script under --inspect flag;
+ and use main process to run CLI debugger.
+ - Listen on port port (default: 9229)
+
+ |
+
+
+
+---
+
+## Enabling remote debugging scenarios
+
+We recommend that you never have the debugger listen on a public IP address. If
+you need to allow remote debugging connections we recommend the use of ssh
+tunnels instead. We provide the following example for illustrative purposes only.
+Please understand the security risk of allowing remote access to a privileged
+service before proceeding.
+
+Let's say you are running Node on remote machine, remote.example.com, that you
+want to be able to debug. On that machine, you should start the node process
+with the inspector listening only to localhost (the default).
+
+```bash
+$ node --inspect server.js
+```
+
+Now, on your local machine from where you want to initiate a debug client
+connection, you can setup an ssh tunnel:
+
+```bash
+$ ssh -L 9221:localhost:9229 user@remote.example.com
+```
+
+This starts a ssh tunnel session where a connection to port 9221 on your local
+machine will be forwarded to port 9229 on remote.example.com. You can now attach
+a debugger such as Chrome DevTools or Visual Studio Code to localhost:9221,
+which should be able to debug as if the Node.js application was running locally.
+
+---
+
+## Legacy Debugger
+
+**The legacy debugger has been deprecated as of Node 7.7.0. Please use --inspect
+and Inspector instead.**
+
+When started with the **--debug** or **--debug-brk** switches in version 7 and
+earlier, Node.js listens for debugging commands defined by the discontinued
+V8 Debugging Protocol on a TCP port, by default `5858`. Any debugger client
+which speaks this protocol can connect to and debug the running process; a
+couple popular ones are listed below.
+
+The V8 Debugging Protocol is no longer maintained or documented.
+
+#### [Built-in Debugger](https://nodejs.org/dist/latest-v6.x/docs/api/debugger.html)
+
+Start `node debug script_name.js` to start your script under Node's builtin
+command-line debugger. Your script starts in another Node process started with
+the `--debug-brk` option, and the initial Node process runs the `_debugger.js`
+script and connects to your target.
+
+#### [node-inspector](https://github.com/node-inspector/node-inspector)
+
+Debug your Node.js app with Chrome DevTools by using an intermediary process
+which translates the Inspector Protocol used in Chromium to the V8 Debugger
+protocol used in Node.js.
+
+
+
+[Inspector Protocol]: https://chromedevtools.github.io/debugger-protocol-viewer/v8/
+[UUID]: https://tools.ietf.org/html/rfc4122
diff --git a/locale/fa/docs/guides/domain-postmortem.md b/locale/fa/docs/guides/domain-postmortem.md
new file mode 100644
index 0000000000000..6426c2a73361a
--- /dev/null
+++ b/locale/fa/docs/guides/domain-postmortem.md
@@ -0,0 +1,444 @@
+---
+title: Domain Module Postmortem
+layout: docs.hbs
+---
+
+# Domain Module Postmortem
+
+## Usability Issues
+
+### Implicit Behavior
+
+It's possible for a developer to create a new domain and then simply run
+`domain.enter()`. Which then acts as a catch-all for any exception in the
+future that couldn't be observed by the thrower. Allowing a module author to
+intercept the exceptions of unrelated code in a different module. Preventing
+the originator of the code from knowing about its own exceptions.
+
+Here's an example of how one indirectly linked modules can affect another:
+
+```js
+// module a.js
+const b = require('./b');
+const c = require('./c');
+
+
+// module b.js
+const d = require('domain').create();
+d.on('error', () => { /* silence everything */ });
+d.enter();
+
+
+// module c.js
+const dep = require('some-dep');
+dep.method(); // Uh-oh! This method doesn't actually exist.
+```
+
+Since module `b` enters the domain but never exits any uncaught exception will
+be swallowed. Leaving module `c` in the dark as to why it didn't run the entire
+script. Leaving a potentially partially populated `module.exports`. Doing this
+is not the same as listening for `'uncaughtException'`. As the latter is
+explicitly meant to globally catch errors. The other issue is that domains are
+processed prior to any `'uncaughtException'` handlers, and prevent them from
+running.
+
+Another issue is that domains route errors automatically if no `'error'`
+handler was set on the event emitter. There is no opt-in mechanism for this,
+and automatically propagates across the entire asynchronous chain. This may
+seem useful at first, but once asynchronous calls are two or more modules deep
+and one of them doesn't include an error handler the creator of the domain will
+suddenly be catching unexpected exceptions, and the thrower's exception will go
+unnoticed by the author.
+
+The following is a simple example of how a missing `'error'` handler allows
+the active domain to hijack the error:
+
+```js
+const domain = require('domain');
+const net = require('net');
+const d = domain.create();
+d.on('error', (err) => console.error(err.message));
+
+d.run(() => net.createServer((c) => {
+ c.end();
+ c.write('bye');
+}).listen(8000));
+```
+
+Even manually removing the connection via `d.remove(c)` does not prevent the
+connection's error from being automatically intercepted.
+
+Failures that plagues both error routing and exception handling are the
+inconsistencies in how errors are bubbled. The following is an example of how
+nested domains will and won't bubble the exception based on when they happen:
+
+```js
+const domain = require('domain');
+const net = require('net');
+const d = domain.create();
+d.on('error', () => console.error('d intercepted an error'));
+
+d.run(() => {
+ const server = net.createServer((c) => {
+ const e = domain.create(); // No 'error' handler being set.
+ e.run(() => {
+ // This will not be caught by d's error handler.
+ setImmediate(() => {
+ throw new Error('thrown from setImmediate');
+ });
+ // Though this one will bubble to d's error handler.
+ throw new Error('immediately thrown');
+ });
+ }).listen(8080);
+});
+```
+
+It may be expected that nested domains always remain nested, and will always
+propagate the exception up the domain stack. Or that exceptions will never
+automatically bubble. Unfortunately both these situations occur, leading to
+potentially confusing behavior that may even be prone to difficult to debug
+timing conflicts.
+
+
+### API Gaps
+
+While APIs based on using `EventEmitter` can use `bind()` and errback style
+callbacks can use `intercept()`, alternative APIs that implicitly bind to the
+active domain must be executed inside of `run()`. Meaning if module authors
+wanted to support domains using a mechanism alternative to those mentioned they
+must manually implement domain support themselves. Instead of being able to
+leverage the implicit mechanisms already in place.
+
+
+### Error Propagation
+
+Propagating errors across nested domains is not straight forward, if even
+possible. Existing documentation shows a simple example of how to `close()` an
+`http` server if there is an error in the request handler. What it does not
+explain is how to close the server if the request handler creates another
+domain instance for another async request. Using the following as a simple
+example of the failing of error propagation:
+
+```js
+const d1 = domain.create();
+d1.foo = true; // custom member to make more visible in console
+d1.on('error', (er) => { /* handle error */ });
+
+d1.run(() => setTimeout(() => {
+ const d2 = domain.create();
+ d2.bar = 43;
+ d2.on('error', (er) => console.error(er.message, domain._stack));
+ d2.run(() => {
+ setTimeout(() => {
+ setTimeout(() => {
+ throw new Error('outer');
+ });
+ throw new Error('inner');
+ });
+ });
+}));
+```
+
+Even in the case that the domain instances are being used for local storage so
+access to resources are made available there is still no way to allow the error
+to continue propagating from `d2` back to `d1`. Quick inspection may tell us
+that simply throwing from `d2`'s domain `'error'` handler would allow `d1` to
+then catch the exception and execute its own error handler. Though that is not
+the case. Upon inspection of `domain._stack` you'll see that the stack only
+contains `d2`.
+
+This may be considered a failing of the API, but even if it did operate in this
+way there is still the issue of transmitting the fact that a branch in the
+asynchronous execution has failed, and that all further operations in that
+branch must cease. In the example of the http request handler, if we fire off
+several asynchronous requests and each one then `write()`'s data back to the
+client many more errors will arise from attempting to `write()` to a closed
+handle. More on this in _Resource Cleanup on Exception_.
+
+
+### Resource Cleanup on Exception
+
+The following script contains a more complex example of properly cleaning up
+in a small resource dependency tree in the case that an exception occurs in a
+given connection or any of its dependencies. Breaking down the script into its
+basic operations:
+
+```js
+'use strict';
+
+const domain = require('domain');
+const EE = require('events');
+const fs = require('fs');
+const net = require('net');
+const util = require('util');
+const print = process._rawDebug;
+
+const pipeList = [];
+const FILENAME = '/tmp/tmp.tmp';
+const PIPENAME = '/tmp/node-domain-example-';
+const FILESIZE = 1024;
+let uid = 0;
+
+// Setting up temporary resources
+const buf = Buffer.alloc(FILESIZE);
+for (let i = 0; i < buf.length; i++)
+ buf[i] = ((Math.random() * 1e3) % 78) + 48; // Basic ASCII
+fs.writeFileSync(FILENAME, buf);
+
+function ConnectionResource(c) {
+ EE.call(this);
+ this._connection = c;
+ this._alive = true;
+ this._domain = domain.create();
+ this._id = Math.random().toString(32).substr(2).substr(0, 8) + (++uid);
+
+ this._domain.add(c);
+ this._domain.on('error', () => {
+ this._alive = false;
+ });
+}
+util.inherits(ConnectionResource, EE);
+
+ConnectionResource.prototype.end = function end(chunk) {
+ this._alive = false;
+ this._connection.end(chunk);
+ this.emit('end');
+};
+
+ConnectionResource.prototype.isAlive = function isAlive() {
+ return this._alive;
+};
+
+ConnectionResource.prototype.id = function id() {
+ return this._id;
+};
+
+ConnectionResource.prototype.write = function write(chunk) {
+ this.emit('data', chunk);
+ return this._connection.write(chunk);
+};
+
+// Example begin
+net.createServer((c) => {
+ const cr = new ConnectionResource(c);
+
+ const d1 = domain.create();
+ fs.open(FILENAME, 'r', d1.intercept((fd) => {
+ streamInParts(fd, cr, 0);
+ }));
+
+ pipeData(cr);
+
+ c.on('close', () => cr.end());
+}).listen(8080);
+
+function streamInParts(fd, cr, pos) {
+ const d2 = domain.create();
+ const alive = true;
+ d2.on('error', (er) => {
+ print('d2 error:', er.message);
+ cr.end();
+ });
+ fs.read(fd, Buffer.alloc(10), 0, 10, pos, d2.intercept((bRead, buf) => {
+ if (!cr.isAlive()) {
+ return fs.close(fd);
+ }
+ if (cr._connection.bytesWritten < FILESIZE) {
+ // Documentation says callback is optional, but doesn't mention that if
+ // the write fails an exception will be thrown.
+ const goodtogo = cr.write(buf);
+ if (goodtogo) {
+ setTimeout(() => streamInParts(fd, cr, pos + bRead), 1000);
+ } else {
+ cr._connection.once('drain', () => streamInParts(fd, cr, pos + bRead));
+ }
+ return;
+ }
+ cr.end(buf);
+ fs.close(fd);
+ }));
+}
+
+function pipeData(cr) {
+ const pname = PIPENAME + cr.id();
+ const ps = net.createServer();
+ const d3 = domain.create();
+ const connectionList = [];
+ d3.on('error', (er) => {
+ print('d3 error:', er.message);
+ cr.end();
+ });
+ d3.add(ps);
+ ps.on('connection', (conn) => {
+ connectionList.push(conn);
+ conn.on('data', () => {}); // don't care about incoming data.
+ conn.on('close', () => {
+ connectionList.splice(connectionList.indexOf(conn), 1);
+ });
+ });
+ cr.on('data', (chunk) => {
+ for (let i = 0; i < connectionList.length; i++) {
+ connectionList[i].write(chunk);
+ }
+ });
+ cr.on('end', () => {
+ for (let i = 0; i < connectionList.length; i++) {
+ connectionList[i].end();
+ }
+ ps.close();
+ });
+ pipeList.push(pname);
+ ps.listen(pname);
+}
+
+process.on('SIGINT', () => process.exit());
+process.on('exit', () => {
+ try {
+ for (let i = 0; i < pipeList.length; i++) {
+ fs.unlinkSync(pipeList[i]);
+ }
+ fs.unlinkSync(FILENAME);
+ } catch (e) { }
+});
+
+```
+
+- When a new connection happens, concurrently:
+ - Open a file on the file system
+ - Open Pipe to unique socket
+- Read a chunk of the file asynchronously
+- Write chunk to both the TCP connection and any listening sockets
+- If any of these resources error, notify all other attached resources that
+ they need to clean up and shutdown
+
+As we can see from this example a lot more must be done to properly clean up
+resources when something fails than what can be done strictly through the
+domain API. All that domains offer is an exception aggregation mechanism. Even
+the potentially useful ability to propagate data with the domain is easily
+countered, in this example, by passing the needed resources as a function
+argument.
+
+One problem domains perpetuated was the supposed simplicity of being able to
+continue execution, contrary to what the documentation stated, of the
+application despite an unexpected exception. This example demonstrates the
+fallacy behind that idea.
+
+Attempting proper resource cleanup on unexpected exception becomes more complex
+as the application itself grows in complexity. This example only has 3 basic
+resources in play, and all of them with a clear dependency path. If an
+application uses something like shared resources or resource reuse the ability
+to cleanup, and properly test that cleanup has been done, grows greatly.
+
+In the end, in terms of handling errors, domains aren't much more than a
+glorified `'uncaughtException'` handler. Except with more implicit and
+unobservable behavior by third-parties.
+
+
+### Resource Propagation
+
+Another use case for domains was to use it to propagate data along asynchronous
+data paths. One problematic point is the ambiguity of when to expect the
+correct domain when there are multiple in the stack (which must be assumed if
+the async stack works with other modules). Also the conflict between being
+able to depend on a domain for error handling while also having it available to
+retrieve the necessary data.
+
+The following is a involved example demonstrating the failing using domains to
+propagate data along asynchronous stacks:
+
+```js
+const domain = require('domain');
+const net = require('net');
+
+const server = net.createServer((c) => {
+ // Use a domain to propagate data across events within the
+ // connection so that we don't have to pass arguments
+ // everywhere.
+ const d = domain.create();
+ d.data = { connection: c };
+ d.add(c);
+ // Mock class that does some useless async data transformation
+ // for demonstration purposes.
+ const ds = new DataStream(dataTransformed);
+ c.on('data', (chunk) => ds.data(chunk));
+}).listen(8080, () => console.log('listening on 8080'));
+
+function dataTransformed(chunk) {
+ // FAIL! Because the DataStream instance also created a
+ // domain we have now lost the active domain we had
+ // hoped to use.
+ domain.active.data.connection.write(chunk);
+}
+
+function DataStream(cb) {
+ this.cb = cb;
+ // DataStream wants to use domains for data propagation too!
+ // Unfortunately this will conflict with any domain that
+ // already exists.
+ this.domain = domain.create();
+ this.domain.data = { inst: this };
+}
+
+DataStream.prototype.data = function data(chunk) {
+ // This code is self contained, but pretend it's a complex
+ // operation that crosses at least one other module. So
+ // passing along "this", etc., is not easy.
+ this.domain.run(() => {
+ // Simulate an async operation that does the data transform.
+ setImmediate(() => {
+ for (let i = 0; i < chunk.length; i++)
+ chunk[i] = ((chunk[i] + Math.random() * 100) % 96) + 33;
+ // Grab the instance from the active domain and use that
+ // to call the user's callback.
+ const self = domain.active.data.inst;
+ self.cb(chunk);
+ });
+ });
+};
+```
+
+The above shows that it is difficult to have more than one asynchronous API
+attempt to use domains to propagate data. This example could possibly be fixed
+by assigning `parent: domain.active` in the `DataStream` constructor. Then
+restoring it via `domain.active = domain.active.data.parent` just before the
+user's callback is called. Also the instantiation of `DataStream` in the
+`'connection'` callback must be run inside `d.run()`, instead of simply using
+`d.add(c)`, otherwise there will be no active domain.
+
+In short, for this to have a prayer of a chance usage would need to strictly
+adhere to a set of guidelines that would be difficult to enforce or test.
+
+
+## Performance Issues
+
+A significant deterrent from using domains is the overhead. Using node's
+built-in http benchmark, `http_simple.js`, without domains it can handle over
+22,000 requests/second. Whereas if it's run with `NODE_USE_DOMAINS=1` that
+number drops down to under 17,000 requests/second. In this case there is only
+a single global domain. If we edit the benchmark so the http request callback
+creates a new domain instance performance drops further to 15,000
+requests/second.
+
+While this probably wouldn't affect a server only serving a few hundred or even
+a thousand requests per second, the amount of overhead is directly proportional
+to the number of asynchronous requests made. So if a single connection needs to
+connect to several other services all of those will contribute to the overall
+latency of delivering the final product to the client.
+
+Using `AsyncWrap` and tracking the number of times
+`init`/`pre`/`post`/`destroy` are called in the mentioned benchmark we find
+that the sum of all events called is over 170,000 times per second. This means
+even adding 1 microsecond overhead per call for any type of setup or tear down
+will result in a 17% performance loss. Granted, this is for the optimized
+scenario of the benchmark, but I believe this demonstrates the necessity for a
+mechanism such as domain to be as cheap to run as possible.
+
+
+## Looking Ahead
+
+The domain module has been soft deprecated since Dec 2014, but has not yet been
+removed because node offers no alternative functionality at the moment. As of
+this writing there is ongoing work building out the `AsyncWrap` API and a
+proposal for Zones being prepared for the TC39. At such time there is suitable
+functionality to replace domains it will undergo the full deprecation cycle and
+eventually be removed from core.
diff --git a/locale/fa/docs/guides/dont-block-the-event-loop.md b/locale/fa/docs/guides/dont-block-the-event-loop.md
new file mode 100644
index 0000000000000..9e3e2c79905e1
--- /dev/null
+++ b/locale/fa/docs/guides/dont-block-the-event-loop.md
@@ -0,0 +1,476 @@
+---
+title: Don't Block the Event Loop (or the Worker Pool)
+layout: docs.hbs
+---
+
+# Don't Block the Event Loop (or the Worker Pool)
+
+## Should you read this guide?
+If you're writing anything more complicated than a brief command-line script, reading this should help you write higher-performance, more-secure applications.
+
+This document is written with Node servers in mind, but the concepts apply to complex Node applications as well.
+Where OS-specific details vary, this document is Linux-centric.
+
+## TL; DR
+Node.js runs JavaScript code in the Event Loop (initialization and callbacks), and offers a Worker Pool to handle expensive tasks like file I/O.
+Node scales well, sometimes better than more heavyweight approaches like Apache.
+The secret to Node's scalability is that it uses a small number of threads to handle many clients.
+If Node can make do with fewer threads, then it can spend more of your system's time and memory working on clients rather than on paying space and time overheads for threads (memory, context-switching).
+But because Node has only a few threads, you must structure your application to use them wisely.
+
+Here's a good rule of thumb for keeping your Node server speedy:
+*Node is fast when the work associated with each client at any given time is "small"*.
+
+This applies to callbacks on the Event Loop and tasks on the Worker Pool.
+
+## Why should I avoid blocking the Event Loop and the Worker Pool?
+Node uses a small number of threads to handle many clients.
+In Node there are two types of threads: one Event Loop (aka the main loop, main thread, event thread, etc.), and a pool of `k` Workers in a Worker Pool (aka the threadpool).
+
+If a thread is taking a long time to execute a callback (Event Loop) or a task (Worker), we call it "blocked".
+While a thread is blocked working on behalf of one client, it cannot handle requests from any other clients.
+This provides two motivations for blocking neither the Event Loop nor the Worker Pool:
+
+1. Performance: If you regularly perform heavyweight activity on either type of thread, the *throughput* (requests/second) of your server will suffer.
+2. Security: If it is possible that for certain input one of your threads might block, a malicious client could submit this "evil input", make your threads block, and keep them from working on other clients. This would be a [Denial of Service](https://en.wikipedia.org/wiki/Denial-of-service_attack) attack.
+
+## A quick review of Node
+
+Node uses the Event-Driven Architecture: it has an Event Loop for orchestration and a Worker Pool for expensive tasks.
+
+### What code runs on the Event Loop?
+When they begin, Node applications first complete an initialization phase, `require`'ing modules and registering callbacks for events.
+Node applications then enter the Event Loop, responding to incoming client requests by executing the appropriate callback.
+This callback executes synchronously, and may register asynchronous requests to continue processing after it completes.
+The callbacks for these asynchronous requests will also be executed on the Event Loop.
+
+The Event Loop will also fulfill the non-blocking asynchronous requests made by its callbacks, e.g., network I/O.
+
+In summary, the Event Loop executes the JavaScript callbacks registered for events, and is also responsible for fulfilling non-blocking asynchronous requests like network I/O.
+
+### What code runs on the Worker Pool?
+Node's Worker Pool is implemented in libuv ([docs](http://docs.libuv.org/en/v1.x/threadpool.html)), which exposes a general task submission API.
+
+Node uses the Worker Pool to handle "expensive" tasks.
+This includes I/O for which an operating system does not provide a non-blocking version, as well as particularly CPU-intensive tasks.
+
+These are the Node module APIs that make use of this Worker Pool:
+1. I/O-intensive
+ 1. [DNS](https://nodejs.org/api/dns.html): `dns.lookup()`, `dns.lookupService()`.
+ 2. [File System](https://nodejs.org/api/fs.html#fs_threadpool_usage): All file system APIs except `fs.FSWatcher()` and those that are explicitly synchronous use libuv's threadpool.
+2. CPU-intensive
+ 1. [Crypto](https://nodejs.org/api/crypto.html): `crypto.pbkdf2()`, `crypto.randomBytes()`, `crypto.randomFill()`.
+ 2. [Zlib](https://nodejs.org/api/zlib.html#zlib_threadpool_usage): All zlib APIs except those that are explicitly synchronous use libuv's threadpool.
+
+In many Node applications, these APIs are the only sources of tasks for the Worker Pool. Applications and modules that use a [C++ add-on](https://nodejs.org/api/addons.html) can submit other tasks to the Worker Pool.
+
+For the sake of completeness, we note that when you call one of these APIs from a callback on the Event Loop, the Event Loop pays some minor setup costs as it enters the Node C++ bindings for that API and submits a task to the Worker Pool.
+These costs are negligible compared to the overall cost of the task, which is why the Event Loop is offloading it.
+When submitting one of these tasks to the Worker Pool, Node provides a pointer to the corresponding C++ function in the Node C++ bindings.
+
+### How does Node decide what code to run next?
+Abstractly, the Event Loop and the Worker Pool maintain queues for pending events and pending tasks, respectively.
+
+In truth, the Event Loop does not actually maintain a queue.
+Instead, it has a collection of file descriptors that it asks the operating system to monitor, using a mechanism like [epoll](http://man7.org/linux/man-pages/man7/epoll.7.html) (Linux), [kqueue](https://developer.apple.com/library/content/documentation/Darwin/Conceptual/FSEvents_ProgGuide/KernelQueues/KernelQueues.html) (OSX), event ports (Solaris), or [IOCP](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365198.aspx) (Windows).
+These file descriptors correspond to network sockets, any files it is watching, and so on.
+When the operating system says that one of these file descriptors is ready, the Event Loop translates it to the appropriate event and invokes the callback(s) associated with that event.
+You can learn more about this process [here](https://www.youtube.com/watch?v=P9csgxBgaZ8).
+
+In contrast, the Worker Pool uses a real queue whose entries are tasks to be processed.
+A Worker pops a task from this queue and works on it, and when finished the Worker raises an "At least one task is finished" event for the Event Loop.
+
+### What does this mean for application design?
+In a one-thread-per-client system like Apache, each pending client is assigned its own thread.
+If a thread handling one client blocks, the operating system will interrupt it and give another client a turn.
+The operating system thus ensures that clients that require a small amount of work are not penalized by clients that require more work.
+
+Because Node handles many clients with few threads, if a thread blocks handling one client's request, then pending client requests may not get a turn until the thread finishes its callback or task.
+*The fair treatment of clients is thus the responsibility of your application*.
+This means that you shouldn't do too much work for any client in any single callback or task.
+
+This is part of why Node can scale well, but it also means that you are responsible for ensuring fair scheduling.
+The next sections talk about how to ensure fair scheduling for the Event Loop and for the Worker Pool.
+
+## Don't block the Event Loop
+The Event Loop notices each new client connection and orchestrates the generation of a response.
+All incoming requests and outgoing responses pass through the Event Loop.
+This means that if the Event Loop spends too long at any point, all current and new clients will not get a turn.
+
+You should make sure you never block the Event Loop.
+In other words, each of your JavaScript callbacks should complete quickly.
+This of course also applies to your `await`'s, your `Promise.then`'s, and so on.
+
+A good way to ensure this is to reason about the ["computational complexity"](https://en.wikipedia.org/wiki/Time_complexity) of your callbacks.
+If your callback takes a constant number of steps no matter what its arguments are, then you'll always give every pending client a fair turn.
+If your callback takes a different number of steps depending on its arguments, then you should think about how long the arguments might be.
+
+Example 1: A constant-time callback.
+
+```javascript
+app.get('/constant-time', (req, res) => {
+ res.sendStatus(200);
+});
+```
+
+Example 2: An `O(n)` callback. This callback will run quickly for small `n` and more slowly for large `n`.
+
+```javascript
+app.get('/countToN', (req, res) => {
+ let n = req.query.n;
+
+ // n iterations before giving someone else a turn
+ for (let i = 0; i < n; i++) {
+ console.log(`Iter {$i}`);
+ }
+
+ res.sendStatus(200);
+});
+```
+
+Example 3: An `O(n^2)` callback. This callback will still run quickly for small `n`, but for large `n` it will run much more slowly than the previous `O(n)` example.
+
+```javascript
+app.get('/countToN2', (req, res) => {
+ let n = req.query.n;
+
+ // n^2 iterations before giving someone else a turn
+ for (let i = 0; i < n; i++) {
+ for (let j = 0; j < n; j++) {
+ console.log(`Iter ${i}.${j}`);
+ }
+ }
+
+ res.sendStatus(200);
+});
+```
+
+### How careful should you be?
+Node uses the Google V8 engine for JavaScript, which is quite fast for many common operations.
+Exceptions to this rule are regexps and JSON operations, discussed below.
+
+However, for complex tasks you should consider bounding the input and rejecting inputs that are too long.
+That way, even if your callback has large complexity, by bounding the input you ensure the callback cannot take more than the worst-case time on the longest acceptable input.
+You can then evaluate the worst-case cost of this callback and determine whether its running time is acceptable in your context.
+
+### Blocking the Event Loop: REDOS
+One common way to block the Event Loop disastrously is by using a "vulnerable" [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions).
+
+#### Avoiding vulnerable regular expressions
+A regular expression (regexp) matches an input string against a pattern.
+We usually think of a regexp match as requiring a single pass through the input string --- `O(n)` time where `n` is the length of the input string.
+In many cases, a single pass is indeed all it takes.
+Unfortunately, in some cases the regexp match might require an exponential number of trips through the input string --- `O(2^n)` time.
+An exponential number of trips means that if the engine requires `x` trips to determine a match, it will need `2*x` trips if we add only one more character to the input string.
+Since the number of trips is linearly related to the time required, the effect of this evaluation will be to block the Event Loop.
+
+A *vulnerable regular expression* is one on which your regular expression engine might take exponential time, exposing you to [REDOS](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) on "evil input".
+Whether or not your regular expression pattern is vulnerable (i.e. the regexp engine might take exponential time on it) is actually a difficult question to answer, and varies depending on whether you're using Perl, Python, Ruby, Java, JavaScript, etc., but here are some rules of thumb that apply across all of these languages:
+
+1. Avoid nested quantifiers like `(a+)*`. Node's regexp engine can handle some of these quickly, but others are vulnerable.
+2. Avoid OR's with overlapping clauses, like `(a|a)*`. Again, these are sometimes-fast.
+3. Avoid using backreferences, like `(a.*) \1`. No regexp engine can guarantee evaluating these in linear time.
+4. If you're doing a simple string match, use `indexOf` or the local equivalent. It will be cheaper and will never take more than `O(n)`.
+
+If you aren't sure whether your regular expression is vulnerable, remember that Node generally doesn't have trouble reporting a *match* even for a vulnerable regexp and a long input string.
+The exponential behavior is triggered when there is a mismatch but Node can't be certain until it tries many paths through the input string.
+
+#### A REDOS example
+Here is an example vulnerable regexp exposing its server to REDOS:
+
+```javascript
+app.get('/redos-me', (req, res) => {
+ let filePath = req.query.filePath;
+
+ // REDOS
+ if (fileName.match(/(\/.+)+$/)) {
+ console.log('valid path');
+ }
+ else {
+ console.log('invalid path');
+ }
+
+ res.sendStatus(200);
+});
+```
+
+The vulnerable regexp in this example is a (bad!) way to check for a valid path on Linux.
+It matches strings that are a sequence of "/"-delimited names, like "/a/b/c".
+It is dangerous because it violates rule 1: it has a doubly-nested quantifier.
+
+If a client queries with filePath `///.../\n` (100 /'s followed by a newline character that the regexp's "." won't match), then the Event Loop will take effectively forever, blocking the Event Loop.
+This client's REDOS attack causes all other clients not to get a turn until the regexp match finishes.
+
+For this reason, you should be leery of using complex regular expressions to validate user input.
+
+#### Anti-REDOS Resources
+There are some tools to check your regexps for safety, like
+- [safe-regex](https://github.com/substack/safe-regex)
+- [rxxr2](http://www.cs.bham.ac.uk/~hxt/research/rxxr2/).
+However, neither of these will catch all vulnerable regexps.
+
+Another approach is to use a different regexp engine.
+You could use the [node-re2](https://github.com/uhop/node-re2) module, which uses Google's blazing-fast [RE2](https://github.com/google/re2) regexp engine.
+But be warned, RE2 is not 100% compatible with Node's regexps, so check for regressions if you swap in the node-re2 module to handle your regexps.
+And particularly complicated regexps are not supported by node-re2.
+
+If you're trying to match something "obvious", like a URL or a file path, find an example in a [regexp library](http://www.regexlib.com) or use an npm module, e.g. [ip-regex](https://www.npmjs.com/package/ip-regex).
+
+### Blocking the Event Loop: Node core modules
+Several Node core modules have synchronous expensive APIs, including:
+- [Encryption](https://nodejs.org/api/crypto.html)
+- [Compression](https://nodejs.org/api/zlib.html)
+- [File system](https://nodejs.org/api/fs.html)
+- [Child process](https://nodejs.org/api/child_process.html)
+
+These APIs are expensive, because they involve significant computation (encryption, compression), require I/O (file I/O), or potentially both (child process). These APIs are intended for scripting convenience, but are not intended for use in the server context. If you execute them on the Event Loop, they will take far longer to complete than a typical JavaScript instruction, blocking the Event Loop.
+
+In a server, *you should not use the following synchronous APIs from these modules*:
+- Encryption:
+ - `crypto.randomBytes` (synchronous version)
+ - `crypto.randomFillSync`
+ - `crypto.pbkdf2Sync`
+ - You should also be careful about providing large input to the encryption and decryption routines.
+- Compression:
+ - `zlib.inflateSync`
+ - `zlib.deflateSync`
+- File system:
+ - Do not use the synchronous file system APIs. For example, if the file you access is in a [distributed file system](https://en.wikipedia.org/wiki/Clustered_file_system#Distributed_file_systems) like [NFS](https://en.wikipedia.org/wiki/Network_File_System), access times can vary widely.
+- Child process:
+ - `child_process.spawnSync`
+ - `child_process.execSync`
+ - `child_process.execFileSync`
+
+This list is reasonably complete as of Node v9.
+
+### Blocking the Event Loop: JSON DOS
+`JSON.parse` and `JSON.stringify` are other potentially expensive operations.
+While these are `O(n)` in the length of the input, for large `n` they can take surprisingly long.
+
+If your server manipulates JSON objects, particularly those from a client, you should be cautious about the size of the objects or strings you work with on the Event Loop.
+
+Example: JSON blocking. We create an object `obj` of size 2^21 and `JSON.stringify` it, run `indexOf` on the string, and then JSON.parse it. The `JSON.stringify`'d string is 50MB. It takes 0.7 seconds to stringify the object, 0.03 seconds to indexOf on the 50MB string, and 1.3 seconds to parse the string.
+
+```javascript
+var obj = { a: 1 };
+var niter = 20;
+
+var before, res, took;
+
+for (var i = 0; i < len; i++) {
+ obj = { obj1: obj, obj2: obj }; // Doubles in size each iter
+}
+
+before = process.hrtime();
+res = JSON.stringify(obj);
+took = process.hrtime(n);
+console.log('JSON.stringify took ' + took);
+
+before = process.hrtime();
+res = str.indexOf('nomatch');
+took = process.hrtime(n);
+console.log('Pure indexof took ' + took);
+
+before = process.hrtime();
+res = JSON.parse(str);
+took = process.hrtime(n);
+console.log('JSON.parse took ' + took);
+```
+
+There are npm modules that offer asynchronous JSON APIs. See for example:
+- [JSONStream](https://www.npmjs.com/package/JSONStream), which has stream APIs.
+- [Big-Friendly JSON](https://github.com/philbooth/bfj), which has stream APIs as well as asynchronous versions of the standard JSON APIs using the partitioning-on-the-Event-Loop paradigm outlined below.
+
+### Complex calculations without blocking the Event Loop
+Suppose you want to do complex calculations in JavaScript without blocking the Event Loop.
+You have two options: partitioning or offloading.
+
+#### Partitioning
+You could *partition* your calculations so that each runs on the Event Loop but regularly yields (gives turns to) other pending events.
+In JavaScript it's easy to save the state of an ongoing task in a closure, as shown in example 2 below.
+
+For a simple example, suppose you want to compute the average of the numbers `1` to `n`.
+
+Example 1: Un-partitioned average, costs `O(n)`
+```javascript
+for (let i = 0; i < n; i++)
+ sum += i;
+let avg = sum / n;
+console.log('avg: ' + avg);
+```
+
+Example 2: Partitioned average, each of the `n` asynchronous steps costs `O(1)`.
+```javascript
+function asyncAvg(n, avgCB) {
+ // Save ongoing sum in JS closure.
+ var sum = 0;
+ function help(i, cb) {
+ sum += i;
+ if (i == n) {
+ cb(sum);
+ return;
+ }
+
+ // "Asynchronous recursion".
+ // Schedule next operation asynchronously.
+ setImmediate(help.bind(null, i+1, cb));
+ }
+
+ // Start the helper, with CB to call avgCB.
+ help(1, function(sum){
+ var avg = sum/n;
+ avgCB(avg);
+ });
+}
+
+asyncAvg(n, function(avg){
+ console.log('avg of 1-n: ' + avg);
+});
+```
+
+You can apply this principle to array iterations and so forth.
+
+#### Offloading
+If you need to do something more complex, partitioning is not a good option.
+This is because partitioning uses only the Event Loop, and you won't benefit from multiple cores almost certainly available on your machine.
+*Remember, the Event Loop should orchestrate client requests, not fulfill them itself.*
+For a complicated task, move the work off of the Event Loop onto a Worker Pool.
+
+##### How to offload
+You have two options for a destination Worker Pool to which to offload work.
+1. You can use the built-in Node Worker Pool by developing a [C++ addon](https://nodejs.org/api/addons.html). On older versions of Node, build your C++ addon using [NAN](https://github.com/nodejs/nan), and on newer versions use [N-API](https://nodejs.org/api/n-api.html). [node-webworker-threads](https://www.npmjs.com/package/webworker-threads) offers a JavaScript-only way to access Node's Worker Pool.
+2. You can create and manage your own Worker Pool dedicated to computation rather than Node's I/O-themed Worker Pool. The most straightforward ways to do this is using [Child Process](https://nodejs.org/api/child_process.html) or [Cluster](https://nodejs.org/api/cluster.html).
+
+You should *not* simply create a [Child Process](https://nodejs.org/api/child_process.html) for every client.
+You can receive client requests more quickly than you can create and manage children, and your server might become a [fork bomb](https://en.wikipedia.org/wiki/Fork_bomb).
+
+##### Downside of offloading
+The downside of the offloading approach is that it incurs overhead in the form of *communication costs*.
+Only the Event Loop is allowed to see the "namespace" (JavaScript state) of your application.
+From a Worker, you cannot manipulate a JavaScript object in the Event Loop's namespace.
+Instead, you have to serialize and deserialize any objects you wish to share.
+Then the Worker can operate on its own copy of these object(s) and return the modified object (or a "patch") to the Event Loop.
+
+For serialization concerns, see the section on JSON DOS.
+
+##### Some suggestions for offloading
+You may wish to distinguish between CPU-intensive and I/O-intensive tasks because they have markedly different characteristics.
+
+A CPU-intensive task only makes progress when its Worker is scheduled, and the Worker must be scheduled onto one of your machine's [logical cores](https://nodejs.org/api/os.html#os_os_cpus).
+If you have 4 logical cores and 5 Workers, one of these Workers cannot make progress.
+As a result, you are paying overhead (memory and scheduling costs) for this Worker and getting no return for it.
+
+I/O-intensive tasks involve querying an external service provider (DNS, file system, etc.) and waiting for its response.
+While a Worker with an I/O-intensive task is waiting for its response, it has nothing else to do and can be de-scheduled by the operating system, giving another Worker a chance to submit their request.
+Thus, *I/O-intensive tasks will be making progress even while the associated thread is not running*.
+External service providers like databases and file systems have been highly optimized to handle many pending requests concurrently.
+For example, a file system will examine a large set of pending write and read requests to merge conflicting updates and to retrieve files in an optimal order (e.g. see [these slides](http://researcher.ibm.com/researcher/files/il-AVISHAY/01-block_io-v1.3.pdf)).
+
+If you rely on only one Worker Pool, e.g. the Node Worker Pool, then the differing characteristics of CPU-bound and I/O-bound work may harm your application's performance.
+
+For this reason, you might wish to maintain a separate Computation Worker Pool.
+
+#### Offloading: conclusions
+For simple tasks, like iterating over the elements of an arbitrarily long array, partitioning might be a good option.
+If your computation is more complex, offloading is a better approach: the communication costs, i.e. the overhead of passing serialized objects between the Event Loop and the Worker Pool, are offset by the benefit of using multiple cores.
+
+However, if your server relies heavily on complex calculations, you should think about whether Node is really a good fit. Node excels for I/O-bound work, but for expensive computation it might not be the best option.
+
+If you take the offloading approach, see the section on not blocking the Worker Pool.
+
+## Don't block the Worker Pool
+Node has a Worker Pool composed of `k` Workers.
+If you are using the Offloading paradigm discussed above, you might have a separate Computational Worker Pool, to which the same principles apply.
+In either case, let us assume that `k` is much smaller than the number of clients you might be handling concurrently.
+This is in keeping with Node's "one thread for many clients" philosophy, the secret to its scalability.
+
+As discussed above, each Worker completes its current Task before proceeding to the next one on the Worker Pool queue.
+
+Now, there will be variation in the cost of the Tasks required to handle your clients' requests.
+Some Tasks can be completed quickly (e.g. reading short or cached files, or producing a small number of random bytes), and others will take longer (e.g reading larger or uncached files, or generating more random bytes).
+Your goal should be to *minimize the variation in Task times*, and you should use *Task partitioning* to accomplish this.
+
+### Minimizing the variation in Task times
+If a Worker's current Task is much more expensive than other Tasks, then it will be unavailable to work on other pending Tasks.
+In other words, *each relatively long Task effectively decreases the size of the Worker Pool by one until it is completed*.
+This is undesirable because, up to a point, the more Workers in the Worker Pool, the greater the Worker Pool throughput (tasks/second) and thus the greater the server throughput (client requests/second).
+One client with a relatively expensive Task will decrease the throughput of the Worker Pool, in turn decreasing the throughput of the server.
+
+To avoid this, you should try to minimize variation in the length of Tasks you submit to the Worker Pool.
+While it is appropriate to treat the external systems accessed by your I/O requests (DB, FS, etc.) as black boxes, you should be aware of the relative cost of these I/O requests, and should avoid submitting requests you can expect to be particularly long.
+
+Two examples should illustrate the possible variation in task times.
+
+#### Variation example: Long-running file system reads
+Suppose your server must read files in order to handle some client requests.
+After consulting Node's [File system](https://nodejs.org/api/fs.html) APIs, you opted to use `fs.readFile()` for simplicity.
+However, `fs.readFile()` is ([currently](https://github.com/nodejs/node/pull/17054)) not partitioned: it submits a single `fs.read()` Task spanning the entire file.
+If you read shorter files for some users and longer files for others, `fs.readFile()` may introduce significant variation in Task lengths, to the detriment of Worker Pool throughput.
+
+For a worst-case scenario, suppose an attacker can convince your server to read an *arbitrary* file (this is a [directory traversal vulnerability](https://www.owasp.org/index.php/Path_Traversal)).
+If your server is running Linux, the attacker can name an extremely slow file: [`/dev/random`](http://man7.org/linux/man-pages/man4/random.4.html).
+For all practical purposes, `/dev/random` is infinitely slow, and every Worker asked to read from `/dev/random` will never finish that Task.
+An attacker then submits `k` requests, one for each Worker, and no other client requests that use the Worker Pool will make progress.
+
+#### Variation example: Long-running crypto operations
+Suppose your server generates cryptographically secure random bytes using [`crypto.randomBytes()`](https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback).
+`crypto.randomBytes()` is not partitioned: it creates a single `randomBytes()` Task to generate as many bytes as you requested.
+If you create fewer bytes for some users and more bytes for others, `crypto.randomBytes()` is another source of variation in Task lengths.
+
+### Task partitioning
+Tasks with variable time costs can harm the throughput of the Worker Pool.
+To minimize variation in Task times, as far as possible you should *partition* each Task into comparable-cost sub-Tasks.
+When each sub-Task completes it should submit the next sub-Task, and when the final sub-Task completes it should notify the submitter.
+
+To continue the `fs.readFile()` example, you should instead use `fs.read()` (manual partitioning) or `ReadStream` (automatically partitioned).
+
+The same principle applies to CPU-bound tasks; the `asyncAvg` example might be inappropriate for the Event Loop, but it is well suited to the Worker Pool.
+
+When you partition a Task into sub-Tasks, shorter Tasks expand into a small number of sub-Tasks, and longer Tasks expand into a larger number of sub-Tasks.
+Between each sub-Task of a longer Task, the Worker to which it was assigned can work on a sub-Task from another, shorter, Task, thus improving the overall Task throughput of the Worker Pool.
+
+Note that the number of sub-Tasks completed is not a useful metric for the throughput of the Worker Pool.
+Instead, concern yourself with the number of *Tasks* completed.
+
+### Avoiding Task partitioning
+Recall that the purpose of Task partitioning is to minimize the variation in Task times.
+If you can distinguish between shorter Tasks and longer Tasks (e.g. summing an array vs. sorting an array), you could create one Worker Pool for each class of Task.
+Routing shorter Tasks and longer Tasks to separate Worker Pools is another way to minimize Task time variation.
+
+In favor of this approach, partitioning Tasks incurs overhead (the costs of creating a Worker Pool Task representation and of manipulating the Worker Pool queue), and avoiding partitioning saves you the costs of additional trips to the Worker Pool.
+It also keeps you from making mistakes in partitioning your Tasks.
+
+The downside of this approach is that Workers in all of these Worker Pools will incur space and time overheads and will compete with each other for CPU time.
+Remember that each CPU-bound Task makes progress only while it is scheduled.
+As a result, you should only consider this approach after careful analysis.
+
+### Worker Pool: conclusions
+Whether you use only the Node Worker Pool or maintain separate Worker Pool(s), you should optimize the Task throughput of your Pool(s).
+
+To do this, minimize the variation in Task times by using Task partitioning.
+
+## The risks of npm modules
+While the Node core modules offer building blocks for a wide variety of applications, sometimes something more is needed. Node developers benefit tremendously from the [npm ecosystem](https://www.npmjs.com/), with hundreds of thousands of modules offering functionality to accelerate your development process.
+
+Remember, however, that the majority of these modules are written by third-party developers and are generally released with only best-effort guarantees. A developer using an npm module should be concerned about two things, though the latter is frequently forgotten.
+1. Does it honor its APIs?
+2. Might its APIs block the Event Loop or a Worker?
+Many modules make no effort to indicate the cost of their APIs, to the detriment of the community.
+
+For simple APIs you can estimate the cost of the APIs; the cost of string manipulation isn't hard to fathom.
+But in many cases it's unclear how much an API might cost.
+
+*If you are calling an API that might do something expensive, double-check the cost. Ask the developers to document it, or examine the source code yourself (and submit a PR documenting the cost).*
+
+Remember, even if the API is asynchronous, you don't know how much time it might spend on a Worker or on the Event Loop in each of its partitions.
+For example, suppose in the `asyncAvg` example given above, each call to the helper function summed *half* of the numbers rather than one of them.
+Then this function would still be asynchronous, but the cost of each partition would be `O(n)`, not `O(1)`, making it much less safe to use for arbitrary values of `n`.
+
+## Conclusion
+Node has two types of threads: one Event Loop and `k` Workers.
+The Event Loop is responsible for JavaScript callbacks and non-blocking I/O, and a Worker executes tasks corresponding to C++ code that completes an asynchronous request, including blocking I/O and CPU-intensive work.
+Both types of threads work on no more than one activity at a time.
+If any callback or task takes a long time, the thread running it becomes *blocked*.
+If your application makes blocking callbacks or tasks, this can lead to degraded throughput (clients/second) at best, and complete denial of service at worst.
+
+To write a high-throughput, more DoS-proof web server, you must ensure that on benign and on malicious input, neither your Event Loop nor your Workers will block.
diff --git a/locale/fa/docs/guides/event-loop-timers-and-nexttick.md b/locale/fa/docs/guides/event-loop-timers-and-nexttick.md
new file mode 100644
index 0000000000000..f0896b04ee20a
--- /dev/null
+++ b/locale/fa/docs/guides/event-loop-timers-and-nexttick.md
@@ -0,0 +1,492 @@
+---
+title: The Node.js Event Loop, Timers, and process.nextTick()
+layout: docs.hbs
+---
+
+# The Node.js Event Loop, Timers, and `process.nextTick()`
+
+## What is the Event Loop?
+
+The event loop is what allows Node.js to perform non-blocking I/O
+operations — despite the fact that JavaScript is single-threaded — by
+offloading operations to the system kernel whenever possible.
+
+Since most modern kernels are multi-threaded, they can handle multiple
+operations executing in the background. When one of these operations
+completes, the kernel tells Node.js so that the appropriate callback
+may be added to the **poll** queue to eventually be executed. We'll explain
+this in further detail later in this topic.
+
+## Event Loop Explained
+
+When Node.js starts, it initializes the event loop, processes the
+provided input script (or drops into the [REPL][], which is not covered in
+this document) which may make async API calls, schedule timers, or call
+`process.nextTick()`, then begins processing the event loop.
+
+The following diagram shows a simplified overview of the event loop's
+order of operations.
+
+```
+ ┌───────────────────────────┐
+┌─>│ timers │
+│ └─────────────┬─────────────┘
+│ ┌─────────────┴─────────────┐
+│ │ pending callbacks │
+│ └─────────────┬─────────────┘
+│ ┌─────────────┴─────────────┐
+│ │ idle, prepare │
+│ └─────────────┬─────────────┘ ┌───────────────┐
+│ ┌─────────────┴─────────────┐ │ incoming: │
+│ │ poll │<─────┤ connections, │
+│ └─────────────┬─────────────┘ │ data, etc. │
+│ ┌─────────────┴─────────────┐ └───────────────┘
+│ │ check │
+│ └─────────────┬─────────────┘
+│ ┌─────────────┴─────────────┐
+└──┤ close callbacks │
+ └───────────────────────────┘
+```
+
+*note: each box will be referred to as a "phase" of the event loop.*
+
+Each phase has a FIFO queue of callbacks to execute. While each phase is
+special in its own way, generally, when the event loop enters a given
+phase, it will perform any operations specific to that phase, then
+execute callbacks in that phase's queue until the queue has been
+exhausted or the maximum number of callbacks has executed. When the
+queue has been exhausted or the callback limit is reached, the event
+loop will move to the next phase, and so on.
+
+Since any of these operations may schedule _more_ operations and new
+events processed in the **poll** phase are queued by the kernel, poll
+events can be queued while polling events are being processed. As a
+result, long running callbacks can allow the poll phase to run much
+longer than a timer's threshold. See the [**timers**](#timers) and
+[**poll**](#poll) sections for more details.
+
+_**NOTE:** There is a slight discrepancy between the Windows and the
+Unix/Linux implementation, but that's not important for this
+demonstration. The most important parts are here. There are actually
+seven or eight steps, but the ones we care about — ones that Node.js
+actually uses - are those above._
+
+
+## Phases Overview
+
+* **timers**: this phase executes callbacks scheduled by `setTimeout()`
+ and `setInterval()`.
+* **pending callbacks**: executes I/O callbacks deferred to the next loop
+ iteration.
+* **idle, prepare**: only used internally.
+* **poll**: retrieve new I/O events; execute I/O related callbacks (almost
+ all with the exception of close callbacks, the ones scheduled by timers,
+ and `setImmediate()`); node will block here when appropriate.
+* **check**: `setImmediate()` callbacks are invoked here.
+* **close callbacks**: some close callbacks, e.g. `socket.on('close', ...)`.
+
+Between each run of the event loop, Node.js checks if it is waiting for
+any asynchronous I/O or timers and shuts down cleanly if there are not
+any.
+
+## Phases in Detail
+
+### timers
+
+A timer specifies the **threshold** _after which_ a provided callback
+_may be executed_ rather than the **exact** time a person _wants it to
+be executed_. Timers callbacks will run as early as they can be
+scheduled after the specified amount of time has passed; however,
+Operating System scheduling or the running of other callbacks may delay
+them.
+
+_**Note**: Technically, the [**poll** phase](#poll) controls when timers
+are executed._
+
+For example, say you schedule a timeout to execute after a 100 ms
+threshold, then your script starts asynchronously reading a file which
+takes 95 ms:
+
+```js
+const fs = require('fs');
+
+function someAsyncOperation(callback) {
+ // Assume this takes 95ms to complete
+ fs.readFile('/path/to/file', callback);
+}
+
+const timeoutScheduled = Date.now();
+
+setTimeout(() => {
+ const delay = Date.now() - timeoutScheduled;
+
+ console.log(`${delay}ms have passed since I was scheduled`);
+}, 100);
+
+
+// do someAsyncOperation which takes 95 ms to complete
+someAsyncOperation(() => {
+ const startCallback = Date.now();
+
+ // do something that will take 10ms...
+ while (Date.now() - startCallback < 10) {
+ // do nothing
+ }
+});
+```
+
+When the event loop enters the **poll** phase, it has an empty queue
+(`fs.readFile()` has not completed), so it will wait for the number of ms
+remaining until the soonest timer's threshold is reached. While it is
+waiting 95 ms pass, `fs.readFile()` finishes reading the file and its
+callback which takes 10 ms to complete is added to the **poll** queue and
+executed. When the callback finishes, there are no more callbacks in the
+queue, so the event loop will see that the threshold of the soonest
+timer has been reached then wrap back to the **timers** phase to execute
+the timer's callback. In this example, you will see that the total delay
+between the timer being scheduled and its callback being executed will
+be 105ms.
+
+Note: To prevent the **poll** phase from starving the event loop, [libuv][]
+(the C library that implements the Node.js
+event loop and all of the asynchronous behaviors of the platform)
+also has a hard maximum (system dependent) before it stops polling for
+more events.
+
+### pending callbacks
+
+This phase executes callbacks for some system operations such as types
+of TCP errors. For example if a TCP socket receives `ECONNREFUSED` when
+attempting to connect, some \*nix systems want to wait to report the
+error. This will be queued to execute in the **pending callbacks** phase.
+
+### poll
+
+The **poll** phase has two main functions:
+
+1. Calculating how long it should block and poll for I/O, then
+2. Processing events in the **poll** queue.
+
+When the event loop enters the **poll** phase _and there are no timers
+scheduled_, one of two things will happen:
+
+* _If the **poll** queue **is not empty**_, the event loop will iterate
+through its queue of callbacks executing them synchronously until
+either the queue has been exhausted, or the system-dependent hard limit
+is reached.
+
+* _If the **poll** queue **is empty**_, one of two more things will
+happen:
+ * If scripts have been scheduled by `setImmediate()`, the event loop
+ will end the **poll** phase and continue to the **check** phase to
+ execute those scheduled scripts.
+
+ * If scripts **have not** been scheduled by `setImmediate()`, the
+ event loop will wait for callbacks to be added to the queue, then
+ execute them immediately.
+
+Once the **poll** queue is empty the event loop will check for timers
+_whose time thresholds have been reached_. If one or more timers are
+ready, the event loop will wrap back to the **timers** phase to execute
+those timers' callbacks.
+
+### check
+
+This phase allows a person to execute callbacks immediately after the
+**poll** phase has completed. If the **poll** phase becomes idle and
+scripts have been queued with `setImmediate()`, the event loop may
+continue to the **check** phase rather than waiting.
+
+`setImmediate()` is actually a special timer that runs in a separate
+phase of the event loop. It uses a libuv API that schedules callbacks to
+execute after the **poll** phase has completed.
+
+Generally, as the code is executed, the event loop will eventually hit
+the **poll** phase where it will wait for an incoming connection, request,
+etc. However, if a callback has been scheduled with `setImmediate()`
+and the **poll** phase becomes idle, it will end and continue to the
+**check** phase rather than waiting for **poll** events.
+
+### close callbacks
+
+If a socket or handle is closed abruptly (e.g. `socket.destroy()`), the
+`'close'` event will be emitted in this phase. Otherwise it will be
+emitted via `process.nextTick()`.
+
+## `setImmediate()` vs `setTimeout()`
+
+`setImmediate` and `setTimeout()` are similar, but behave in different
+ways depending on when they are called.
+
+* `setImmediate()` is designed to execute a script once the current
+**poll** phase completes.
+* `setTimeout()` schedules a script to be run after a minimum threshold
+in ms has elapsed.
+
+The order in which the timers are executed will vary depending on the
+context in which they are called. If both are called from within the
+main module, then timing will be bound by the performance of the process
+(which can be impacted by other applications running on the machine).
+
+For example, if we run the following script which is not within an I/O
+cycle (i.e. the main module), the order in which the two timers are
+executed is non-deterministic, as it is bound by the performance of the
+process:
+
+
+```js
+// timeout_vs_immediate.js
+setTimeout(() => {
+ console.log('timeout');
+}, 0);
+
+setImmediate(() => {
+ console.log('immediate');
+});
+```
+
+```
+$ node timeout_vs_immediate.js
+timeout
+immediate
+
+$ node timeout_vs_immediate.js
+immediate
+timeout
+```
+
+However, if you move the two calls within an I/O cycle, the immediate
+callback is always executed first:
+
+```js
+// timeout_vs_immediate.js
+const fs = require('fs');
+
+fs.readFile(__filename, () => {
+ setTimeout(() => {
+ console.log('timeout');
+ }, 0);
+ setImmediate(() => {
+ console.log('immediate');
+ });
+});
+```
+
+```
+$ node timeout_vs_immediate.js
+immediate
+timeout
+
+$ node timeout_vs_immediate.js
+immediate
+timeout
+```
+
+The main advantage to using `setImmediate()` over `setTimeout()` is
+`setImmediate()` will always be executed before any timers if scheduled
+within an I/O cycle, independently of how many timers are present.
+
+## `process.nextTick()`
+
+### Understanding `process.nextTick()`
+
+You may have noticed that `process.nextTick()` was not displayed in the
+diagram, even though it's a part of the asynchronous API. This is because
+`process.nextTick()` is not technically part of the event loop. Instead,
+the `nextTickQueue` will be processed after the current operation
+completes, regardless of the current phase of the event loop.
+
+Looking back at our diagram, any time you call `process.nextTick()` in a
+given phase, all callbacks passed to `process.nextTick()` will be
+resolved before the event loop continues. This can create some bad
+situations because **it allows you to "starve" your I/O by making
+recursive `process.nextTick()` calls**, which prevents the event loop
+from reaching the **poll** phase.
+
+### Why would that be allowed?
+
+Why would something like this be included in Node.js? Part of it is a
+design philosophy where an API should always be asynchronous even where
+it doesn't have to be. Take this code snippet for example:
+
+```js
+function apiCall(arg, callback) {
+ if (typeof arg !== 'string')
+ return process.nextTick(callback,
+ new TypeError('argument should be string'));
+}
+```
+
+The snippet does an argument check and if it's not correct, it will pass
+the error to the callback. The API updated fairly recently to allow
+passing arguments to `process.nextTick()` allowing it to take any
+arguments passed after the callback to be propagated as the arguments to
+the callback so you don't have to nest functions.
+
+What we're doing is passing an error back to the user but only *after*
+we have allowed the rest of the user's code to execute. By using
+`process.nextTick()` we guarantee that `apiCall()` always runs its
+callback *after* the rest of the user's code and *before* the event loop
+is allowed to proceed. To achieve this, the JS call stack is allowed to
+unwind then immediately execute the provided callback which allows a
+person to make recursive calls to `process.nextTick()` without reaching a
+`RangeError: Maximum call stack size exceeded from v8`.
+
+This philosophy can lead to some potentially problematic situations.
+Take this snippet for example:
+
+```js
+let bar;
+
+// this has an asynchronous signature, but calls callback synchronously
+function someAsyncApiCall(callback) { callback(); }
+
+// the callback is called before `someAsyncApiCall` completes.
+someAsyncApiCall(() => {
+ // since someAsyncApiCall has completed, bar hasn't been assigned any value
+ console.log('bar', bar); // undefined
+});
+
+bar = 1;
+```
+
+The user defines `someAsyncApiCall()` to have an asynchronous signature,
+but it actually operates synchronously. When it is called, the callback
+provided to `someAsyncApiCall()` is called in the same phase of the
+event loop because `someAsyncApiCall()` doesn't actually do anything
+asynchronously. As a result, the callback tries to reference `bar` even
+though it may not have that variable in scope yet, because the script has not
+been able to run to completion.
+
+By placing the callback in a `process.nextTick()`, the script still has the
+ability to run to completion, allowing all the variables, functions,
+etc., to be initialized prior to the callback being called. It also has
+the advantage of not allowing the event loop to continue. It may be
+useful for the user to be alerted to an error before the event loop is
+allowed to continue. Here is the previous example using `process.nextTick()`:
+
+```js
+let bar;
+
+function someAsyncApiCall(callback) {
+ process.nextTick(callback);
+}
+
+someAsyncApiCall(() => {
+ console.log('bar', bar); // 1
+});
+
+bar = 1;
+```
+
+Here's another real world example:
+
+```js
+const server = net.createServer(() => {}).listen(8080);
+
+server.on('listening', () => {});
+```
+
+When only a port is passed, the port is bound immediately. So, the
+`'listening'` callback could be called immediately. The problem is that the
+`.on('listening')` callback will not have been set by that time.
+
+To get around this, the `'listening'` event is queued in a `nextTick()`
+to allow the script to run to completion. This allows the user to set
+any event handlers they want.
+
+## `process.nextTick()` vs `setImmediate()`
+
+We have two calls that are similar as far as users are concerned, but
+their names are confusing.
+
+* `process.nextTick()` fires immediately on the same phase
+* `setImmediate()` fires on the following iteration or 'tick' of the
+event loop
+
+In essence, the names should be swapped. `process.nextTick()` fires more
+immediately than `setImmediate()`, but this is an artifact of the past
+which is unlikely to change. Making this switch would break a large
+percentage of the packages on npm. Every day more new modules are being
+added, which means every day we wait, more potential breakages occur.
+While they are confusing, the names themselves won't change.
+
+*We recommend developers use `setImmediate()` in all cases because it's
+easier to reason about (and it leads to code that's compatible with a
+wider variety of environments, like browser JS.)*
+
+## Why use `process.nextTick()`?
+
+There are two main reasons:
+
+1. Allow users to handle errors, cleanup any then unneeded resources, or
+perhaps try the request again before the event loop continues.
+
+2. At times it's necessary to allow a callback to run after the call
+stack has unwound but before the event loop continues.
+
+One example is to match the user's expectations. Simple example:
+
+```js
+const server = net.createServer();
+server.on('connection', (conn) => { });
+
+server.listen(8080);
+server.on('listening', () => { });
+```
+
+Say that `listen()` is run at the beginning of the event loop, but the
+listening callback is placed in a `setImmediate()`. Unless a
+hostname is passed, binding to the port will happen immediately. For
+the event loop to proceed, it must hit the **poll** phase, which means
+there is a non-zero chance that a connection could have been received
+allowing the connection event to be fired before the listening event.
+
+Another example is running a function constructor that was to, say,
+inherit from `EventEmitter` and it wanted to call an event within the
+constructor:
+
+```js
+const EventEmitter = require('events');
+const util = require('util');
+
+function MyEmitter() {
+ EventEmitter.call(this);
+ this.emit('event');
+}
+util.inherits(MyEmitter, EventEmitter);
+
+const myEmitter = new MyEmitter();
+myEmitter.on('event', () => {
+ console.log('an event occurred!');
+});
+```
+
+You can't emit an event from the constructor immediately
+because the script will not have processed to the point where the user
+assigns a callback to that event. So, within the constructor itself,
+you can use `process.nextTick()` to set a callback to emit the event
+after the constructor has finished, which provides the expected results:
+
+```js
+const EventEmitter = require('events');
+const util = require('util');
+
+function MyEmitter() {
+ EventEmitter.call(this);
+
+ // use nextTick to emit the event once a handler is assigned
+ process.nextTick(() => {
+ this.emit('event');
+ });
+}
+util.inherits(MyEmitter, EventEmitter);
+
+const myEmitter = new MyEmitter();
+myEmitter.on('event', () => {
+ console.log('an event occurred!');
+});
+```
+
+[libuv]: http://libuv.org
+[REPL]: https://nodejs.org/api/repl.html#repl_repl
diff --git a/locale/fa/docs/guides/getting-started-guide.md b/locale/fa/docs/guides/getting-started-guide.md
new file mode 100644
index 0000000000000..a66d897400f47
--- /dev/null
+++ b/locale/fa/docs/guides/getting-started-guide.md
@@ -0,0 +1,28 @@
+---
+title: Getting Started Guide
+layout: docs.hbs
+---
+
+# How do I start with Node.js after I installed it?
+
+Once you have installed Node, let's try building our first web server.
+Create a file named "app.js", and paste the following code:
+
+```javascript
+const http = require('http');
+
+const hostname = '127.0.0.1';
+const port = 3000;
+
+const server = http.createServer((req, res) => {
+ res.statusCode = 200;
+ res.setHeader('Content-Type', 'text/plain');
+ res.end('Hello World\n');
+});
+
+server.listen(port, hostname, () => {
+ console.log(`Server running at http://${hostname}:${port}/`);
+});
+```
+
+After that, run your web server using ``` node app.js ```, visit http://localhost:3000, and you will see a message 'Hello World'
diff --git a/locale/fa/docs/guides/index.md b/locale/fa/docs/guides/index.md
new file mode 100644
index 0000000000000..2709e17e05615
--- /dev/null
+++ b/locale/fa/docs/guides/index.md
@@ -0,0 +1,32 @@
+---
+title: Guides
+layout: docs.hbs
+---
+
+# Guides
+
+## General
+
+- [Getting Started Guide](getting-started-guide/)
+- [Debugging - Getting Started](debugging-getting-started/)
+- [Easy profiling for Node.js Applications](simple-profiling/)
+- [Dockerizing a Node.js web app](nodejs-docker-webapp/)
+- [Migrating to safe Buffer constructors](buffer-constructor-deprecation/)
+
+
+## Node.js core concepts
+
+- [Overview of Blocking vs Non-Blocking](blocking-vs-non-blocking/)
+- [The Node.js Event Loop, Timers, and process.nextTick()](event-loop-timers-and-nexttick/)
+- [Don't Block the Event Loop (or the Worker Pool)](dont-block-the-event-loop/)
+- [Timers in Node.js](timers-in-node/)
+
+
+## Module-related guides
+
+- [Anatomy of an HTTP Transaction](anatomy-of-an-http-transaction/)
+- [Working with Different Filesystems](working-with-different-filesystems/)
+- [Backpressuring in Streams](backpressuring-in-streams/)
+- [Domain Module Postmortem](domain-postmortem/)
+- [How to publish N-API package](publishing-napi-modules/)
+- [ABI Stability](abi-stability/)
diff --git a/locale/fa/docs/guides/nodejs-docker-webapp.md b/locale/fa/docs/guides/nodejs-docker-webapp.md
new file mode 100644
index 0000000000000..434154a2f0535
--- /dev/null
+++ b/locale/fa/docs/guides/nodejs-docker-webapp.md
@@ -0,0 +1,274 @@
+---
+title: Dockerizing a Node.js web app
+layout: docs.hbs
+---
+
+# Dockerizing a Node.js web app
+
+The goal of this example is to show you how to get a Node.js application into a
+Docker container. The guide is intended for development, and *not* for a
+production deployment. The guide also assumes you have a working [Docker
+installation](https://docs.docker.com/engine/installation/) and a basic
+understanding of how a Node.js application is structured.
+
+In the first part of this guide we will create a simple web application in
+Node.js, then we will build a Docker image for that application, and lastly we
+will run the image as a container.
+
+Docker allows you to package an application with all of its dependencies into a
+standardized unit, called a container, for software development. A container is
+a stripped-to-basics version of a Linux operating system. An image is software
+you load into a container.
+
+## Create the Node.js app
+
+First, create a new directory where all the files would live. In this directory
+create a `package.json` file that describes your app and its dependencies:
+
+```json
+{
+ "name": "docker_web_app",
+ "version": "1.0.0",
+ "description": "Node.js on Docker",
+ "author": "First Last 
