stackphp · simensen · Jul 30, 2013 · Jul 30, 2013 · Jul 30, 2013
diff --git a/source/_views/default.html b/source/_views/default.html
@@ -15,8 +15,30 @@
         <![endif]-->
     </head>
     <body>
+
+        <div class="jumbotron masthead {% if page.is_homepage %}huge{% endif %}">
+            <h1><a href="{{ site.url }}/">Stack</a></h1>
+            <p class="tagline">Composing <a href="https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernelInterface.php">HttpKernelInterface</a> middlewares since 2013!</p>
+            <p>
+                <ul class="nav nav-pills" style="display: inline-block;">
+                    <li>
+                        <a href="https://github.com/stackphp"><i class="icon-github"></i> stackphp</a>
+                    </li>
+                    <li>
+                        <a href="https://twitter.com/stackphp"><i class="icon-twitter"></i> @stackphp</a>
+                    </li>
+                    <li>
+                        <a href="irc://irc.freenode.net/%23stackphp"><i class="icon-comment"></i> #stackphp</a>
+                    </li>
+                </ul>
+            </p>
+        </div>
+
         <div class="mainContent container">
             <div class="row-fluid">
+
+                <hr>
+
                 {% block content_wrapper %}{% block content %}{% endblock %}{% endblock %}
             </div>
         </div>

diff --git a/source/_views/spec.html b/source/_views/spec.html
@@ -0,0 +1,12 @@
+{% extends "default.html" %}
+{% block content_wrapper %}
+    <div class="spec-meta">
+        <h2>{{ page.title }} <span class="label">{{ page.status }}</span></h2>
+    </div>
+    <section class="spec-body">
+
+        {% block content %}
+            <p>This proposal has no content.</p>
+        {% endblock %}
+    </section>
+{% endblock %}
diff --git a/source/css/style.css b/source/css/style.css
@@ -1,3 +1,22 @@
+.anchor {
+    font-size: .75em;
+    text-decoration: none;
+    visibility: hidden;
+}
+
+h2:hover .anchor {
+    visibility: visible;
+    text-decoration: none;
+}
+
+h3 a, h3 a:hover {
+    color: inherit;
+    text-decoration: none;
+}
+
+h2 .label,
+h3 .label { vertical-align: middle; }
+
 .jumbotron {
     text-align: center;
     margin: 2em 0;
@@ -12,14 +31,20 @@
 }
 
 .jumbotron h1 {
+    display: inline-block;
+    font-size: 4em;
+    line-height: 1em;
+}
+
+.jumbotron h1 a {
     display: inline-block;
     background-image: url(stack-logo.png);
     background-position: left;
     background-repeat: no-repeat;
     background-size: contain;
-    font-size: 5em;
-    line-height: 1em;
     text-indent: 1em;
+    color: inherit;
+    text-decoration: none;
 }
 
 .jumbotron p.tagline {
@@ -107,7 +132,7 @@ ol.conventions .no {
 }
 
 @media (max-width: 767px) {
-    .jumbotron a.btn {
+    .jumbotron .nav a.btn {
         font-size: 12px;
         padding: 5px 9px;
     }
@@ -121,18 +146,23 @@ ol.conventions .no {
         margin-top: -0.2em;
     }
 
+    .conventions-and-protocols div.row-fluid h3,
     .middlewares div.row-fluid h3 {
         margin-top: 20px;
     }
 }
 
 @media (min-width: 768px) {
-    .jumbotron {
+    .jumbotron.huge {
         font-size: 2em;
         margin-bottom: 2em;
     }
 
-    .jumbotron a.btn {
+    .jumbotron .nav {
+        margin-bottom: 0;
+    }
+
+    .jumbotron .nav a.btn {
         margin-top: 1em;
     }
 
@@ -145,6 +175,7 @@ ol.conventions .no {
         margin-top: 10px;
     }
 
+    .conventions-and-protocols div.row-fluid:not(:nth-of-type(1)),
     .middlewares div.row-fluid:not(:nth-of-type(1)) {
         margin-top: 2em;
     }

diff --git a/source/index.html b/source/index.html
@@ -1,28 +1,9 @@
 ---
 layout: default
+is_homepage: true
 ---
 {% block full_title %}{{ site.title }} &mdash; {{ site.subtitle }}{% endblock %}
 {% block content %}
-<div class="jumbotron masthead">
-    <h1>Stack</h1>
-    <p class="tagline">Composing <a href="https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernelInterface.php">HttpKernelInterface</a> middlewares since 2013!</p>
-    <p>
-        <ul class="nav nav-pills" style="display: inline-block;">
-            <li>
-                <a href="https://github.com/stackphp"><i class="icon-github"></i> stackphp</a>
-            </li>
-            <li>
-                <a href="https://twitter.com/stackphp"><i class="icon-twitter"></i> @stackphp</a>
-            </li>
-            <li>
-                <a href="irc://irc.freenode.net/%23stackphp"><i class="icon-comment"></i> #stackphp</a>
-            </li>
-        </ul>
-    </p>
-</div>
-
-<hr>
-
 <div class="about text">
     <h2>A common layer</h2>
     <p>
@@ -168,32 +149,71 @@ <h3>Backstage</h3>
     </div>
 </div>
 
-<!--
 <hr>
 
-<div class="examples">
-    <h2>How do I use it?</h2>
-    <pre><code class="php">use Symfony\Component\HttpFoundation\Request;
-use Symfony\Component\HttpKernel\HttpCache\Store;
-
-// This can be **any** HttpKernelInterface based application
-$app = new Silex\Application();
-$app->get('/', function () {
-    return 'Hello World!';
-});
-
-// Extend the behaviour of the application with some middlewares
-$stack = (new Stack\Builder())
-    ->push('Stack\Session')
-    ->push('Symfony\Component\HttpKernel\HttpCache\HttpCache', new Store(__DIR__.'/cache'));
-$app = $stack->resolve($app);
-
-// Front controller is business as usual
-$request = Request::createFromGlobals();
-$response = $app->handle($request)->send();
-$app->terminate($request, $response);</code></pre>
+<div class="conventions-and-protocols">
+    <h2>
+        <a name="conventions-and-protocols"></a>
+        Conventions and Protocols
+        <a class="anchor" href="#conventions-and-protocols">
+            <i class="icon icon-link"></i>
+        </a>
+    </h2>
+    <p>
+        In order to further the goal of interoperability between disparate
+        <code>HttpKernelInterface</code> implementations, Stack  tries to
+        avoid imposing interfaces and instead relies on conventions and
+        protocols for the purpose of integration. The following is a list of
+        community driven proposals for Stack conventions and protocols.
+    </p>
+
+    <div class="row-fluid">
+        <div class="span6">
+            <h3><a href="{{ site.url }}/specs/0/">0 Proposals</a> <span class="label">Draft</span></h3>
+            <p>
+                Specification for how community driven Stack proposals will be
+                written and managed.
+            </p>
+            <div class="btn-group">
+                <a class="btn" href="{{ site.url }}/specs/0/"><i class="icon icon-book"></i> Proposal</a>
+            </div>
+        </div>
+        <div class="span6">
+            <h3><a href="{{ site.url }}/specs/1/">1 Core</a> <span class="label">Draft</span></h3>
+            <p>
+                Specification for writing and interacting with Stack middlewares
+                and applications.
+            </p>
+            <div class="btn-group">
+                <a class="btn" href="{{ site.url }}/specs/1/"><i class="icon icon-book"></i> Proposal</a>
+            </div>
+        </div>
+    </div>
+    <div class="row-fluid">
+        <div class="span6">
+            <h3><a href="{{ site.url }}/specs/2/">2 Authentication</a> <span class="label">Draft</span></h3>
+            <p>
+                Specification for authentication middlewares to follow in order
+                for applications and authorization middlewares to be able to
+                interact with each other.
+            </p>
+            <div class="btn-group">
+                <a class="btn" href="{{ site.url }}/specs/2/"><i class="icon icon-book"></i> Proposal</a>
+            </div>
+        </div>
+        <div class="span6">
+            <h3><a href="{{ site.url }}/specs/3/">3 Authorization</a> <span class="label">Draft</span></h3>
+            <p>
+                Specification for authorization middlewares to follow in order
+                for applications and authentication middlewares to be able to
+                interact with each other.
+            </p>
+            <div class="btn-group">
+                <a class="btn" href="{{ site.url }}/specs/3/"><i class="icon icon-book"></i> Proposal</a>
+            </div>
+        </div>
+    </div>
 </div>
--->
 
 <footer class="authors container">
     <p class="lead">Brought to you by</p>

diff --git a/source/specs/0.md b/source/specs/0.md
@@ -0,0 +1,24 @@
+---
+layout: spec
+title: 0 Proposals
+status: draft
+---
+
+Specification for how community driven Stack proposals will be written and
+managed.
+
+ * Name: {{ page.title }}
+ * Editor: Beau Simensen <[beau@dflydev.com](mailto:beau@dflydev.com)>
+
+
+### Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
+
+
+### Goals
+
+ * To define a workflow for community driven Stack proposals.
+
diff --git a/source/specs/1.md b/source/specs/1.md
@@ -0,0 +1,24 @@
+---
+layout: spec
+title: 1 Core
+status: draft
+---
+
+Specification for writing and interacting with Stack middlewares and
+applications.
+
+ * Name: {{ page.title }}
+ * Editor: Beau Simensen <[beau@dflydev.com](mailto:beau@dflydev.com)>
+
+
+### Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
+
+
+### Goals
+
+ * Specify requirements for a Stack middleware
+
diff --git a/source/specs/2.md b/source/specs/2.md
@@ -0,0 +1,66 @@
+---
+layout: spec
+title: 2 Authentication
+status: draft
+---
+
+This document proposes conventions for authentication middlewares to follow in
+order for applications and authorization middlewares to be able to interact
+with each other.
+
+ * Name: {{ page.title }}
+ * Editor: Beau Simensen <[beau@dflydev.com](mailto:beau@dflydev.com)>
+
+
+### Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
+
+
+### Goals
+
+ * To allow authentication middlewares to communicate when a request has been
+   authenticated.
+ * To allow other middlewares or applications to communicate whether or not
+   the authentication was accepted (for example, authorization failed or is
+   required).
+ * To allow for some coexistence between multiple Stack authentiation
+   middlewares for the same request.
+
+
+### Stack Authentication Middlewares
+
+#### Authentication
+
+A Stack authentication middleware is free to use whatever means necessary to
+authenticate a request. The end result of a successfully authenticated request
+is that the `stack.authentication.token` attribute is set on the request.
+
+If a request has authentication credentials that are invalid for any reason a
+Stack authentication middleware MAY immediately challenge or return another
+reaponse (for example, a 400 error response).
+
+If a request already has the `stack.authentication.token` attribute set a Stack
+authentication middleware MUST NOT attempt to further authenticate the request.
+However, the Stack authentication middleware MAY act further upon inspecting
+the response.
+
+
+#### Integration with Stack Authorization
+
+Stack authentication middlewares SHOULD inspect the response from the wrapped
+app to see if it has a status code of `401` and a `WWW-Authenticate: Stack`
+header. In this case, the Stack authentication middleware can use its own best
+judgement to determine whether or not it should issue a challenge.
+
+Modifying or replacing the response is allowed but a Stack authentication
+middleware MUST NOT challenge unless the response is in this state. If a Stack
+authentication middleware does not change the `WWW-Authenticate` value other
+Stack authentication middlewares will be given an opportunity to challenge.
+
+
+### Implementations
+
+ * [dflydev/stack-hawk](https://github.com/dflydev/dflydev-stack-hawk)