Restructe layout, add README and config page, etc..

Resolves #205

Signed-off-by: Ivan Kozlovic <ivan@synadia.com>

nats-server/configuration/websocket/README.md

@@ -0,0 +1,12 @@
+# Websocket
+
+*Supported since NATS Server version 2.2*
+
+Websocket support can be enabled in the server and may be used alongside the
+traditional TCP socket connections.  TLS, compression and
+Origin Header checking are supported.
+
+**Important**
+
+- NATS Supports only Websocket data frames in Binary, not Text format (https://tools.ietf.org/html/rfc6455#section-5.6). The server will always send in Binary and your clients MUST send in Binary too.
+- For writers of client libraries: a Websocket frame is not guaranteed to contain a full NATS protocol (actually will generally not). Any data from a frame must be going through a parser that can handle partial protocols. See the protocol description [here](../../../nats-protocol/nats-protocol/README.md).

nats-server/configuration/websocket/websocket_conf.md

@@ -0,0 +1,158 @@
+# Configuration
+
+To enable websocket support in the server, add a `websocket` configuration
+block in the server's configuration file like the following:
+
+```
+websocket {
+    # Specify a host and port to listen for websocket connections
+    #
+    # listen: "host:port"
+
+    # It can also be configured with individual parameters,
+    # namely host and port.
+    #
+    # host: "hostname"
+    port: 443
+
+    # This will optionally specify what host:port for websocket
+    # connections to be advertised in the cluster.
+    #
+    # advertise: "host:port"
+
+    # TLS configuration is required by default
+    #
+    tls {
+      cert_file: "/path/to/cert.pem"
+      key_file: "/path/to/key.pem"
+    }
+
+    # For test environments, you can disable the need for TLS
+    # by explicitly setting this option to `true`
+    #
+    # no_tls: true
+
+    # [Cross-origin resource sharing option](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). When set to `true`, the HTTP origin header must match the request’s hostname.
+    # The default is `false`.
+    #
+    # same_origin: true
+
+    # [Cross-origin resource sharing option](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). List of accepted origins. When empty, and `same_origin` is `false`, clients from any origin are allowed to connect.
+    # This list specifies the only accepted values for the client's request Origin header. The scheme,
+    # host and port must match. By convention, the absence of TCP port in the URL will be port 80
+    # for an "http://" scheme, and 443 for "https://".
+    #
+    # allowed_origins [
+    #    "http://www.example.com"
+    #    "https://www.other-example.com"
+    # ]
+
+    # This enables support for compressed websocket frames
+    # in the server. For compression to be used, both server
+    # and client have to support it.
+    #
+    # compression: true
+
+    # This is the total time allowed for the server to
+    # read the client request and write the response back
+    # to the client. This includes the time needed for the
+    # TLS handshake.
+    #
+    # handshake_timeout: "2s"
+
+    # Name for an HTTP cookie, that if present will be used as a client JWT.
+    # If the client specifies a JWT in the CONNECT protocol, this option is ignored.
+    # The cookie should be set by the HTTP server as described [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies).
+    # This setting is useful when generating NATS `Bearer` client JWTs as the
+    # result of some authentication mechanism. The HTTP server after correct
+    # authentication can issue a JWT for the user, that is set securely preventing
+    # access by unintended scripts. Note these JWTs must be [NATS JWTs](https://docs.nats.io/nats-server/configuration/securing_nats/jwt).
+    #
+    # jwt_cookie: "my_jwt_cookie_name"
+
+    # If no user name is provided when a websocket client connects, will default
+    # this user name in the authentication phase. If specified, this will
+    # override, for websocket clients, any `no_auth_user` value defined in the
+    # main configuration file.
+    # Note that this is not compatible with running the server in operator mode.
+    #
+    # no_auth_user: "my_username_for_apps_not_providing_credentials"
+
+    # See below to know what is the normal way of limiting websocket clients
+    # to specific users.
+    # If there are no users specified in the configuration, this simple authorization
+    # block allows you to override the values that would be configured in the
+    # equivalent block in the main section.
+    #
+    # authorization {
+    #     # If this is specified, the client has to provide the same username
+    #     # and password to be able to connect.
+    #     # username: "my_user_name"
+    #     # password: "my_password"
+    #
+    #     # If this is specified, the password field in the CONNECT has to
+    #     # match this token.
+    #     # token: "my_token"
+    #
+    #     # This overrides the main's authorization timeout. For consistency
+    #     # with the main's authorization configuration block, this is expressed
+    #     # as a number of seconds.
+    #     # timeout: 2.0
+    #}
+}
+```
+
+## Authorization of Websocket Users
+
+A new field when configuring users allows you to restrict which type of connections are allowed for a specific user.
+
+Consider this configuration:
+
+```
+authorization {
+  users [
+    {user: foo password: foopwd, permission: {...}}
+    {user: bar password: barpwd, permission: {...}}
+  ]
+}
+```
+
+If a websocket client were to connect and use the username `foo` and password `foopwd`, it would be accepted.
+Now suppose that you would want websocket client to only be accepted if it connected using the username `bar`
+and password `barpwd`, then you would use the option `allowed_connection_types` to restrict which type
+of connections can bind to this user.
+
+```
+authorization {
+  users [
+    {user: foo password: foopwd, permission: {...}}
+    {user: bar password: barpwd, permission: {...}, allowed_connection_types: ["WEBSOCKET"]}
+  ]
+}
+```
+
+The option `allowed_connection_types` (also can be named `connection_types` or `clients`) as you can see
+is a list, and you can allow several type of clients. Suppose you want the user `bar` to accept both
+standard NATS clients and websocket clients, you would configure the user like this:
+
+```
+authorization {
+  users [
+    {user: foo password: foopwd, permission: {...}}
+    {user: bar password: barpwd, permission: {...}, allowed_connection_types: ["STANDARD", "WEBSOCKET"]}
+  ]
+}
+```
+
+The absence of `allowed_connection_types` means that all type of connections are allowed (the default behavior).
+
+The possible values are currently:
+* `STANDARD`
+* `WEBSOCKET`
+* `LEAFNODE`
+* `MQTT`
+
+## Leaf nodes connections
+
+You can configure remote Leaf node connections so that they connect to the Websocket port instead of the Leaf node port.
+See [Leafnode](../leafnodes/leafnode_conf.md#connecting-using-websocket-protocol) section.