doc/spec: update

doc/spec.md

@@ -13,5 +13,104 @@ the complexity of the setup increases.
 
 We need a better option.
 
-Iconia is a service gateway designed to help alleviate these problems while
-maintaining the 
+Iconia is a service gateway that integrates into [Caddy][caddy] to allow for a
+better experience operating complicated applications at scale. The ultimate
+goal of Iconia is to allow services to not require a direct TCP line-of-fire 
+from the load balancer to the backend services. Instead the Iconia agent would
+connect to the load balancer and redirect traffic to the backend, much like it
+would in service meshes like Envoy or Istio.
+
+### Name Origin
+
+The name of Iconia is a reference to the [Iconian gateway][gateway] from the
+Star Trek franchise. It is a gateway that allows for instant travel to distant
+points in the galaxy in ways that bypass shields and other forms of security. 
+The name is used here because Iconia is a gateway to distant services that
+bypasses NAT and other ways that ports get blocked.
+
+## Components
+
+Iconia is made up of several components:
+
+- [Caddy][caddy] as the ingress/TLS terminating component
+- The Iconia agent running alongside the application being exposed to the world
+- The application being exposed via Iconia
+
+### Caddy Plugin
+
+The Caddy plugin for Iconia MUST perform the following operations:
+
+- Gather metrics about the performance of each backend:
+  - Roundtrip time
+  - Time to first byte
+  - Number of connections
+  - Time it takes to do healthchecks
+  - A healthcheck metric defined by the backend application
+- Gather metrics:
+  - Number of connected backends
+  - Number of authentication failures
+- Have some method to intelligently select backends based on the following 
+  criteria:
+  - Load of the backend service instance in question
+  - Client remote IP address and port number
+  - Backend health status (IE: it MUST NOT route to backends that are marked
+    as unhealthy)
+- Expose a protocol or method for backend services to connect to the 
+  concentrator
+  - Evaluate [smux][smux], [SSH][ssh] and [Quic][quic]
+  - Ensure that only authorized agents are allowed to register as backends
+- Expose an API for controlling Iconia operations
+  - List active backends
+  - See details about a given backend by connection ID
+  - Kill an arbitrary backend by connection ID
+- Log messages to the standard Caddy logging sink
+- Route requests and responses to and from the discovered backend 
+  efficiently
+
+The Caddy plugin for Iconia MUST support allowing backends for multiple hosts
+to connect via the same TCP/UDP port. 
+
+### Iconia Agent
+
+The Iconia agent MUST perform the following operations:
+
+- Discover/gather configuration information from the environment and filesystem
+- Connect to the gateway server in a durable and fault-tolerant manner
+- Authenticate to the gateway server
+- Listen for incoming TCP sessions from the gateway server and route them to the
+  backend service
+- Utilize the [PROXY protocol][proxyprotocol] to ensure that the backend service
+  has accurate information about client IP addresses
+
+### Backend Service
+
+Backend services for Iconia MUST have the following properties:
+
+- Understand the [PROXY protocol][proxyprotocol] to ensure that the backend 
+  service has accurate information about client IP addresses
+- Expose a healthcheck route:
+  - On the HTTP host `iconia-healthcheck`
+  - With the path `/health`
+  - That MAY return `200` if everything is healthy with the body `OK`
+  - And also MAY return `500` if everything is NOT healthy with the body
+    containing a site-defined error message explaining what the issue is
+  - This healthcheck MAY include the response header `X-Iconia-Load` to send the
+    gateway a site-defined load metric to help the gateway choose the backend
+    with the least load
+- Accepts connections over TCP to a known port
+
+## Caveats
+
+This will undoubtedly add a slight amount of latency to standard HTTP operations.
+Applications that are latency sensitive should probably avoid using this tool in
+favor of traditional exposure methods.
+
+The Go HTTP/2 stack doesn't currently support connection hijacking. This will be
+needed in order to have the most efficient routing possible.
+
+[caddy]: https://caddyserver.com
+[gateway]: https://memory-alpha.fandom.com/wiki/Iconian_gateway
+[smux]: https://github.com/xtaci/smux
+[ssh]: https://godoc.org/golang.org/x/crypto/ssh
+[quic]: https://godoc.org/github.com/lucas-clemente/quic-go
+[proxyprotocol]: https://github.com/joyent/haproxy-1.5/blob/master/doc/proxy-protocol.txt