From: Christopher <chris@entropealabs.com>
Date: Tue, 18 Feb 2020 14:58:58 +0000 (-0600)
Subject: update readme and docs
X-Git-Url: http://git.entropealabs.com/?a=commitdiff_plain;h=9b7efd919c39016036e61f51354532ef8bb4a077;p=wampex_router.git

update readme and docs
---

diff --git a/README.md b/README.md
index a6dd6c9..123107b 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,177 @@
-# Wampex
+# WAMPex
 
-**TODO: Add description**
+WAMPex is a client library for the [WAMP protocol](https://wamp-proto.org/index.html)
+
+This client library currently implements the [Basic Profile](https://wamp-proto.org/_static/gen/wamp_latest.html#basic-and-advanced-profiles)
+
+This means, currently, there is no authentication, but it is on the roadmap.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `wampex` to your list of dependencies in `mix.exs`:
+Currently it's not available on hex.pm. I want to get a little more real-world testing done before committing to the implementation. However, it is available on Gitlab. You can add the following to your `mix.exs` file to use it.
 
 ```elixir
 def deps do
   [
-    {:wampex, "~> 0.1.0"}
+    {:wampex,
+       git: "https://gitlab.com/entropealabs/wampex",
+       tag: "f998f7280ae671de08b391155d935ae370fa3cad"}
   ]
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/wampex](https://hexdocs.pm/wampex).
+## Documentation
+
+Docs are available at [HexDocs](https://hexdocs.pm/wampex)
+
+## Usage
+
+You can see a full example app, emulating a Smart Home and backend system [here](https://gitlab.com/entropealabs/wampex_example_app)
+
+Currently the only transport supported is WebSockets, but raw TCP is planned for the near future.
+
+WAMPex defaults to WebSocket as the transport and MessagePack as the serialization format.
+
+A simple [Session](https://wamp-proto.org/_static/gen/wamp_latest.html#sessions) can be configured like so.
+
+```elixir
+alias Wampex.{Realm, Session}
+alias Wampex.Role.{Callee, Caller, Publisher, Subscriber}
+
+url = "http://localhost:18080/ws"
+realm = %Realm{name: "com.myrealm"}
+
+roles = [Callee, Caller, Publisher, Subscriber]
+session = Session.new(url, realm, controller_roles)
+
+Wampex.start_link(name: Connection, session: session)
+```
+
+The name can be anything you want, it is required, and must be unique among multiple WAMPex instances. See the [example application](https://gitlab.com/entropealabs/wampex_example_app) for an example of running multiple connections/sessions.
+
+There are behaviours for transports and serializers if you wanted to write your own.
+
+You can override the default serializer and transport like this.
+
+```elixir
+alias Wampex.{Realm, Session}
+alias Wampex.Role.{Callee, Caller, Publisher, Subscriber}
+alias Wampex.Serializer.JSON
+alias Wampex.Transport.WebSocket
+
+url = "http://localhost:18080/ws"
+realm = %Realm{name: "com.myrealm"}
+
+roles = [Callee, Caller, Publisher, Subscriber]
+session = Session.new(url, realm, controller_roles, WebSocket, "wamp.2.json", JSON)
+
+Wampex.start_link(name: Connection, session: session)
+```
+
+The protocol uses a registered [WebSocket subprotocol](https://wamp-proto.org/_static/gen/wamp_latest.html#websocket-transport), there are several values available. You need to ensure that the [Router](https://wamp-proto.org/_static/gen/wamp_latest.html#peers-and-roles) that you connect to also supports the subprotocol.
+
+### Details
+
+WAMPex currently maps each session to a seperate transport connection. This means there is a new conection per instance of WAMPex.
+
+The Session management is handled by a state machine, written using [StatesLanguage](https://github.com/citybaseinc/states_language). The JSON looks like this.
+
+```json
+{
+  "Comment": "Session State Machine",
+  "StartAt": "WaitForTransport",
+  "States": {
+    "WaitForTransport": {
+      "Type": "Task",
+      "Resource": "InitTransport",
+      "TransitionEvent": "{:connected, true}",
+      "Next": "Init",
+      "Catch": [
+        {
+          "ErrorEquals": ["{:connected, false}"],
+          "Next": "Abort"
+        }
+      ]
+    },
+    "Init": {
+      "Type": "Task",
+      "Resource": "Hello",
+      "TransitionEvent": ":hello_sent",
+      "Next": "Established",
+      "Catch": [
+        {
+          "ErrorEquals": [":abort"],
+          "Next": "Abort"
+        }
+        
+      ]
+    },
+    "Established": {
+      "Type": "Choice",
+      "Resource": "Established",
+      "Choices": [
+        {
+          "StringEquals": ":message_received",
+          "Next": "HandleMessage"
+        },
+        {
+          "StringEquals": ":goodbye",
+          "Next": "GoodBye"
+        },
+        {
+          "StringEquals": ":abort",
+          "Next": "Abort"
+        }
+      ]
+    },
+    "HandleMessage": {
+      "Type": "Choice",
+      "Resource": "HandleMessage",
+      "Choices": [
+        {
+          "StringEquals": ":noop",
+          "Next": "Established"
+        },
+        {
+          "StringEquals": ":event",
+          "Next": "Event"
+        },
+        {
+          "StringEquals": ":invocation",
+          "Next": "Invocation"
+        },
+        {
+          "StringEquals": ":abort",
+          "Next": "Abort"
+        },
+        {
+          "StringEquals": ":goodbye",
+          "Next": "GoodBye"
+        }
+      ]
+    },
+    "Event": {
+      "Type": "Task",
+      "Resource": "HandleEvent",
+      "Next": "Established"
+    },
+    "Invocation": {
+      "Type": "Task",
+      "Resource": "HandleInvocation",
+      "Next": "Established"
+    },
+    "GoodBye": {
+      "Type": "Task",
+      "Resource": "GoodBye",
+      "End": true
+    },
+    "Abort": {
+      "Type": "Task",
+      "Resource": "Abort",
+      "End": true
+    }
+  }
+}
+```
 
+You can copy and paste this snippet into the JSON input at https://citybaseinc.github.io/states-language-editor/ to edit and visualize the state machine.
diff --git a/mix.exs b/mix.exs
index 5b92a55..e2d9279 100644
--- a/mix.exs
+++ b/mix.exs
@@ -17,7 +17,12 @@ defmodule Wampex.MixProject do
         "coveralls.html": :test,
         all_tests: :test
       ],
-      test_coverage: [tool: ExCoveralls]
+      test_coverage: [tool: ExCoveralls],
+      docs: [
+        main: "readme",
+        extras: ["README.md"],
+        assets: "assets"
+      ]
     ]
   end