Multi page manual (#5110)

1 files changed, 41 insertions, 0 deletions

diff --git a/docs/examples/tcp_echo.md b/docs/examples/tcp_echo.md
new file mode 100644
index 000000000..d7c2e9e72
--- /dev/null
+++ b/docs/examples/tcp_echo.md
@@ -0,0 +1,41 @@
+## TCP echo server
+
+This is an example of a simple server which accepts connections on port 8080,
+and returns to the client anything it sends.
+
+```ts
+const listener = Deno.listen({ port: 8080 });
+console.log("listening on 0.0.0.0:8080");
+for await (const conn of listener) {
+  Deno.copy(conn, conn);
+}
+```
+
+When this program is started, it throws PermissionDenied error.
+
+```shell
+$ deno run https://deno.land/std/examples/echo_server.ts
+error: Uncaught PermissionDenied: network access to "0.0.0.0:8080", run again with the --allow-net flag
+► $deno$/dispatch_json.ts:40:11
+    at DenoError ($deno$/errors.ts:20:5)
+    ...
+```
+
+For security reasons, Deno does not allow programs to access the network without
+explicit permission. To allow accessing the network, use a command-line flag:
+
+```shell
+$ deno run --allow-net https://deno.land/std/examples/echo_server.ts
+```
+
+To test it, try sending data to it with netcat:
+
+```shell
+$ nc localhost 8080
+hello world
+hello world
+```
+
+Like the `cat.ts` example, the `copy()` function here also does not make
+unnecessary memory copies. It receives a packet from the kernel and sends back,
+without further complexity.