Add docs on caching and private endpoints. Closes #138 (#162)

* docs(): Change 'srcipts' to 'src' for default script location. Add info on script source file shorthand property.

* docs(cache): add info on caching the requests.

* docs(socket): Add info on private endpoints.

docs/cheatsheet/web/index.html

@@ -101,6 +101,12 @@ <h4>Custom headers</h4>
     'Content-Type': 'application/json'
   }
 })</code></pre>
+      <h4>Cache</h4>
+      <pre data-type="socket"><code class="lang-yaml">endpoints:
+  list:
+    cache: 30</code></pre>
+      <pre><code class="lang-js">// skip cache set in the socket.yml
+s.get('countries/list', {__skip_cache: 1})</code></pre>
     </section>
     <!--
 
@@ -590,7 +596,7 @@ <h4>Configure hosting options</h4>
     </section>
     <!--
 
-      ====
+      ==== SOCKET 1
 
 --><section data-tag="socket" class="c-column">
     <h3>Basics</h3>
@@ -614,7 +620,11 @@ <h4>Define endpoints</h4>
       title:
         type: string
       author:
-        type: integer</code></pre>
+        type: integer
+    # cache a GET request for 5 seconds
+    cache: 5
+    # restrict access to admin only
+    private: true</code></pre>
         <h4>Define real-time endpoints</h4>
         <div>
           To learn about Channels, view <a data-tab="server" href="#server">Server Cheatsheet</a>
@@ -667,7 +677,7 @@ <h4>Example config</h4>
       API keys section at (https://home.openweathermap.org/api_keys).
     required: true</code></pre>
       </section><!--
-
+    === SOCKET 2
 --><section data-tag="socket" class="c-column">
     <h3>Data Classes</h3>
     <h4>Define class</h4>

docs/docs/building-sockets/endpoints.md

@@ -3,7 +3,18 @@ The is the most important part of the Syncano Socket configuration file. This is
 
 ## Scripts
 
-When you define an endpoint, you can point to the script code by adding one of these properties:
+When you define an endpoint, Syncano will assume that there's a script in the `./src` with the
+same name. So with an endpoint defined this way:
+
+```yaml
+endpoints:
+  create_internets_now:
+    parameters: ...
+```
+
+Syncano will run a `./src/create_internets_now.js` script.
+
+Alternatively, you can point to the script code by adding one of these properties:
 - `source`
 - `file`
 
@@ -16,18 +27,50 @@ When you define an endpoint, you can point to the script code by adding one of t
       data.chat.get(id).return()
 ```
 
-The `data.chat.get(id).return()` is a script code that will get executed when the `get_object` endpoint is called. The script code defined this way can span across multiple lines of the config file.
+The `data.chat.get(id).return()` is a script code that will get executed when the `get_obj` endpoint is called. The script code defined this way can span across multiple lines of the config file.
 
-While the `source` method is great for one-liners, it might get cumbersome with more sophisticated script code. That's why the recommended way of passing the script code into endpoints is with `file` property:
+With the `file` property, you can define an alternative path for your script:
 
 ```yaml
 endpoints:
   get_obj:
-    file: ./scripts/get_obj.js
+    file: ./src/different_than_endpoint_name.js
 ```
 
 `file` value is a relative path to the file containing the script code. The `socket.yml` location is the root.
 
+## Caching
+
+You can allow for caching the GET requests to your endpoints. Add a cache property to the endpoint definition to enable caching:
+
+```yaml
+endpoint:
+  i_will_be_cached:
+    cache: 5
+```
+
+Now, the response from `i_will_be_cached` endpoint will be cached for `5 seconds`.
+
+> valid cache property values are in a 0-1800 (exclusive) range with a floating point precision.
+
+The cache property can be ignored on the client side. To do that, add `__skip_cache=1` query param to the GET request:
+
+```js
+s.get('socket/with_cache', { '__skip_cache': 1 })
+```
+
+## Private endpoints
+
+By default, endpoints are public, which means that anyone can execute the underlying script. To change this setting add a `private: true` param to the endpoint definition:
+
+```yaml
+endpoints:
+  restricted:
+    private: true
+```
+
+Endpoints with this parameter, will be accessible with an account key only. They are suitable for hiding away Socket settings and configuration options. End users of your app won't have access to them.
+
 ## Channels
 
 Real-Time Channels are a way of providing real-time publish/subscribe functionality in Syncano.
@@ -53,7 +96,7 @@ Since the yaml file will accept any property, you can add your own notes to any
 ```yaml
 endpoints:
   send_email:
-    file: ./scripts/send_email.js
+    file: ./src/send_email.js
     parameters:
       email:
         type: string

docs/docs/building-sockets/socket-file-structure.md

@@ -15,7 +15,7 @@ When you do a `npx syncano-cli init` from the Syncano CLI, a `syncano` folder wi
 |syncano.yml|This file contains an Instance configuration. It lists Instance variables and plugins used by the CLI. It's in the root of `syncano` directory.|
 |package.json|You can use `npm` packages within your Syncano scripts. `npm i <package> --save-dev` and require them as you would in a regular project.|
 |`/socket/` directory|Each socket installed in your Instance will have its own directory. It will contain:|
-|`/scripts/`directory|Will contain all the scripts that are executed by endpoints defined in the `socket.yml` file|
+|`/src/`directory|Will contain all the scripts that are executed by endpoints defined in the `socket.yml` file|
 |socket.yml|Socket configuration file. It contains socket specific information like:<br/>-endpoints definitions<br/>-class schema configuration<br/>-hosting configuration|
 
 

docs/docs/building-sockets/yaml-specification.md

@@ -63,7 +63,7 @@ While the `source` method is great for one-liners, it might get cumbersome with
 ```yaml
 endpoints:
   get_obj:
-    file: ./scripts/get_obj.js
+    file: ./src/get_obj.js
 ```
 
 `file` value is a relative path to the file containing the script code. The`socket.yml` location is the root.
@@ -76,9 +76,9 @@ By default, an endpoint will execute the same script on any type of HTTP request
 endpoints:  
   endpoint_separate_by_http_method:
     GET:
-      file: ./scripts/get_obj.js
+      file: ./src/get_obj.js
     POST:
-    	file: ./scripts/create_object.js
+    	file: ./src/create_object.js
 ```
 
 ### Endpoint documentation
@@ -87,7 +87,7 @@ Since the yml file will accept any property, you can add your own notes to any p
 ```yaml
 endpoints:
   send_email:
-    file: ./scripts/send_email.js
+    file: ./src/send_email.js
     parameters:
       email:
         type: string

docs/docs/project/overview.md

@@ -25,8 +25,8 @@ my-project/.gitignore
 my-project/syncano
 my-project/syncano/hello
 my-project/syncano/hello/package.json
-my-project/syncano/hello/scripts
-my-project/syncano/hello/scripts/hello.js
+my-project/syncano/hello/src
+my-project/syncano/hello/src/hello.js
 my_project/syncano/hello/socket.yml
 my_project/syncano/package.json
 my_project/syncano/syncano.yml

packages/lib-js-client/docs/channels.md

@@ -30,11 +30,11 @@ endpoints:
   global-messages:
     channel: global-messages
   create-message:
-    file: scripts/create-message.js
+    file: src/create-message.js
 ```
 
 ```js
-// chat/scripts/create-message.js
+// chat/src/create-message.js
 import {data, channel} from 'syncano-server'
 
 data.messages
@@ -55,17 +55,17 @@ endpoints:
   private-messages:
     channel: private-messages.{room}
   create-message:
-    file: scripts/create-message.js
+    file: src/create-message.js
 ```
 
 ```js
-// chat/scripts/create-message.js
+// chat/src/create-message.js
 import {data, channel} from 'syncano-server'
 
 data.messages
   .create({
     room_id: ARGS.room_id,
-    content: ARGS.content, 
+    content: ARGS.content,
     user: META.user.id
   })
   .then(message => {
@@ -89,23 +89,23 @@ endpoints:
   get:
     channel: notifications.{user}
   notify:
-    file: scripts/notify.js
+    file: src/notify.js
 ```
 
-Then you can subscribe to channel by passing socket and endpoint name. User channels require `user_key` to be send in payload. 
+Then you can subscribe to channel by passing socket and endpoint name. User channels require `user_key` to be send in payload.
 
 ```js
 s.subscribe('notifications/get', {user_key: 'USER_KEY'}, notification => {
   // Handle notification
 })
 ```
 
-To publish to the user channel, you have to know it's `username`. 
+To publish to the user channel, you have to know it's `username`.
 
 > In channel name `notifications.{user}` - `{user}` must always be `username`, not id or any other property.
 
 ```js
-// notifications/scripts/notify.js
+// notifications/src/notify.js
 import {data, channel} from 'syncano-server'
 
 data.notifications