Skip to content

Commit f8321b2

Browse files
simensensimensen
committed
Framework for handling specs and proposals.
1 parent 212397c commit f8321b2

File tree

7 files changed

+266
-48
lines changed

7 files changed

+266
-48
lines changed

‎source/_views/default.html

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,30 @@
1515
<![endif]-->
1616
</head>
1717
<body>
18+
19+
<div class="jumbotron masthead {% if page.is_homepage %}huge{% endif %}">
20+
<h1><a href="{{ site.url }}/">Stack</a></h1>
21+
<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>
22+
<p>
23+
<ul class="nav nav-pills" style="display: inline-block;">
24+
<li>
25+
<a href="https://github.com/stackphp"><i class="icon-github"></i> stackphp</a>
26+
</li>
27+
<li>
28+
<a href="https://twitter.com/stackphp"><i class="icon-twitter"></i> @stackphp</a>
29+
</li>
30+
<li>
31+
<a href="irc://irc.freenode.net/%23stackphp"><i class="icon-comment"></i> #stackphp</a>
32+
</li>
33+
</ul>
34+
</p>
35+
</div>
36+
1837
<div class="mainContent container">
1938
<div class="row-fluid">
39+
40+
<hr>
41+
2042
{% block content_wrapper %}{% block content %}{% endblock %}{% endblock %}
2143
</div>
2244
</div>

‎source/_views/spec.html

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{% extends "default.html" %}
2+
{% block content_wrapper %}
3+
<div class="spec-meta">
4+
<h2>{{ page.title }} <span class="label">{{ page.status }}</span></h2>
5+
</div>
6+
<section class="spec-body">
7+
8+
{% block content %}
9+
<p>This proposal has no content.</p>
10+
{% endblock %}
11+
</section>
12+
{% endblock %}

‎source/css/style.css

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
.anchor {
2+
font-size: .75em;
3+
text-decoration: none;
4+
visibility: hidden;
5+
}
6+
7+
h2:hover .anchor {
8+
visibility: visible;
9+
text-decoration: none;
10+
}
11+
12+
h3 a, h3 a:hover {
13+
color: inherit;
14+
text-decoration: none;
15+
}
16+
17+
h2 .label,
18+
h3 .label { vertical-align: middle; }
19+
120
.jumbotron {
221
text-align: center;
322
margin: 2em 0;
@@ -12,14 +31,20 @@
1231
}
1332

1433
.jumbotron h1 {
34+
display: inline-block;
35+
font-size: 4em;
36+
line-height: 1em;
37+
}
38+
39+
.jumbotron h1 a {
1540
display: inline-block;
1641
background-image: url(stack-logo.png);
1742
background-position: left;
1843
background-repeat: no-repeat;
1944
background-size: contain;
20-
font-size: 5em;
21-
line-height: 1em;
2245
text-indent: 1em;
46+
color: inherit;
47+
text-decoration: none;
2348
}
2449

2550
.jumbotron p.tagline {
@@ -107,7 +132,7 @@ ol.conventions .no {
107132
}
108133

109134
@media (max-width: 767px) {
110-
.jumbotron a.btn {
135+
.jumbotron .nav a.btn {
111136
font-size: 12px;
112137
padding: 5px 9px;
113138
}
@@ -127,12 +152,16 @@ ol.conventions .no {
127152
}
128153

129154
@media (min-width: 768px) {
130-
.jumbotron {
155+
.jumbotron.huge {
131156
font-size: 2em;
132157
margin-bottom: 2em;
133158
}
134159

135-
.jumbotron a.btn {
160+
.jumbotron .nav {
161+
margin-bottom: 0;
162+
}
163+
164+
.jumbotron .nav a.btn {
136165
margin-top: 1em;
137166
}
138167

‎source/index.html

Lines changed: 53 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,9 @@
11
---
22
layout: default
3+
is_homepage: true
34
---
45
{% block full_title %}{{ site.title }} &mdash; {{ site.subtitle }}{% endblock %}
56
{% block content %}
6-
<div class="jumbotron masthead">
7-
<h1>Stack</h1>
8-
<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>
9-
<p>
10-
<ul class="nav nav-pills" style="display: inline-block;">
11-
<li>
12-
<a href="https://github.com/stackphp"><i class="icon-github"></i> stackphp</a>
13-
</li>
14-
<li>
15-
<a href="https://twitter.com/stackphp"><i class="icon-twitter"></i> @stackphp</a>
16-
</li>
17-
<li>
18-
<a href="irc://irc.freenode.net/%23stackphp"><i class="icon-comment"></i> #stackphp</a>
19-
</li>
20-
</ul>
21-
</p>
22-
</div>
23-
24-
<hr>
25-
267
<div class="about text">
278
<h2>A common layer</h2>
289
<p>
@@ -168,32 +149,61 @@ <h3>Backstage</h3>
168149
</div>
169150
</div>
170151

171-
<!--
172152
<hr>
173153

174-
<div class="examples">
175-
<h2>How do I use it?</h2>
176-
<pre><code class="php">use Symfony\Component\HttpFoundation\Request;
177-
use Symfony\Component\HttpKernel\HttpCache\Store;
178-
179-
// This can be **any** HttpKernelInterface based application
180-
$app = new Silex\Application();
181-
$app->get('/', function () {
182-
return 'Hello World!';
183-
});
184-
185-
// Extend the behaviour of the application with some middlewares
186-
$stack = (new Stack\Builder())
187-
->push('Stack\Session')
188-
->push('Symfony\Component\HttpKernel\HttpCache\HttpCache', new Store(__DIR__.'/cache'));
189-
$app = $stack->resolve($app);
190-
191-
// Front controller is business as usual
192-
$request = Request::createFromGlobals();
193-
$response = $app->handle($request)->send();
194-
$app->terminate($request, $response);</code></pre>
154+
<div class="conventions-and-protocols">
155+
<h2>
156+
<a name="conventions-and-protocols"></a>
157+
Conventions and Protocols
158+
<a class="anchor" href="#conventions-and-protocols">
159+
<i class="icon icon-link"></i>
160+
</a>
161+
</h2>
162+
<p>
163+
In order to further the goal of interoperability between disparate
164+
<code>HttpKernelInterface</code> implementations, Stack tries to
165+
avoid imposing interfaces and instead relies on conventions and
166+
protocols for the purpose of integration. The following is a list of
167+
community driven proposals for Stack conventions and protocols.
168+
</p>
169+
170+
<div class="row-fluid">
171+
<div class="span6">
172+
<h3><a href="{{ site.url }}/specs/1/">1 - Proposals</a> <span class="label">Draft</span></h3>
173+
<p>
174+
Specification for how community driven Stack proposals will be
175+
written and managed.
176+
</p>
177+
<div class="btn-group">
178+
<a class="btn" href="{{ site.url }}/specs/1/"><i class="icon icon-book"></i> Specification</a>
179+
</div>
180+
</div>
181+
<div class="span6">
182+
<h3><a href="{{ site.url }}/specs/2/">2 - Authentication</a> <span class="label">Draft</span></h3>
183+
<p>
184+
Specification for authentication middlewares to follow in order
185+
for applications and authorization middlewares to be able to
186+
interact with each other.
187+
</p>
188+
<div class="btn-group">
189+
<a class="btn" href="{{ site.url }}/specs/2/"><i class="icon icon-book"></i> Specification</a>
190+
</div>
191+
</div>
192+
</div>
193+
<div class="row-fluid">
194+
<div class="span6">
195+
<h3><a href="{{ site.url }}/specs/3/">3 - Authorization</a> <span class="label">Draft</span></h3>
196+
<p>
197+
Specification for authorization middlewares to follow in order
198+
for applications and authentication middlewares to be able to
199+
interact with each other.
200+
</p>
201+
<div class="btn-group">
202+
<a class="btn" href="{{ site.url }}/specs/2/"><i class="icon icon-book"></i> Specification</a>
203+
</div>
204+
</div>
205+
</div>
195206
</div>
196-
-->
197207

198208
<footer class="authors container">
199209
<p class="lead">Brought to you by</p>

‎source/specs/1.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
layout: spec
3+
title: 1 Proposals
4+
status: draft
5+
---
6+
7+
Specification for how community driven Stack proposals will be written and
8+
managed.
9+
10+
* Name: {{ page.title }}
11+
* Editor: Beau Simensen <[beau@dflydev.com](mailto:beau@dflydev.com)>
12+
13+
14+
### Language
15+
16+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
17+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
18+
interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
19+
20+
21+
### Goals
22+
23+
* To define a workflow for community driven Stack proposals.
24+

‎source/specs/2.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
layout: spec
3+
title: 2 Authentication
4+
status: draft
5+
---
6+
7+
This document proposes conventions for authentication middlewares to follow in
8+
order for applications and authorization middlewares to be able to interact
9+
with each other.
10+
11+
* Name: {{ page.title }}
12+
* Editor: Beau Simensen <[beau@dflydev.com](mailto:beau@dflydev.com)>
13+
14+
15+
### Language
16+
17+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
18+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
19+
interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
20+
21+
22+
### Goals
23+
24+
* To allow authentication middlewares to communicate when a request has been
25+
authenticated.
26+
* To allow other middlewares or applications to communicate whether or not
27+
the authentication was accepted (for example, authorization failed or is
28+
required).
29+
* To allow for some coexistence between multiple Stack authentiation
30+
middlewares for the same request.
31+
32+
33+
### Stack Authentication Middlewares
34+
35+
#### Authentication
36+
37+
A Stack authentication middleware is free to use whatever means necessary to
38+
authenticate a request. The end result of a successfully authenticated request
39+
is that the `stack.authentication.token` attribute is set on the request.
40+
41+
If a request has authentication credentials that are invalid for any reason a
42+
Stack authentication middleware MAY immediately challenge or return another
43+
reaponse (for example, a 400 error response).
44+
45+
If a request already has the `stack.authentication.token` attribute set a Stack
46+
authentication middleware MUST NOT attempt to further authenticate the request.
47+
However, the Stack authentication middleware MAY act further upon inspecting
48+
the response.
49+
50+
51+
#### Integration with Stack Authorization
52+
53+
Stack authentication middlewares SHOULD inspect the response from the wrapped
54+
app to see if it has a status code of `401` and a `WWW-Authenticate: Stack`
55+
header. In this case, the Stack authentication middleware can use its own best
56+
judgement to determine whether or not it should issue a challenge.
57+
58+
Modifying or replacing the response is allowed but a Stack authentication
59+
middleware MUST NOT challenge unless the response is in this state. If a Stack
60+
authentication middleware does not change the `WWW-Authenticate` value other
61+
Stack authentication middlewares will be given an opportunity to challenge.
62+
63+
64+
### Implementations
65+
66+
* [dflydev/stack-hawk](https://github.com/dflydev/dflydev-stack-hawk)

‎source/specs/3.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
layout: spec
3+
title: 3 Authorization
4+
status: draft
5+
---
6+
7+
This document proposes conventions for authorization middlewares to follow in
8+
order for applications and authentication middlewares to be able to interact
9+
with each other.
10+
11+
* Name: {{ page.title }}
12+
* Editor: Beau Simensen <[beau@dflydev.com](mailto:beau@dflydev.com)>
13+
14+
15+
### Language
16+
17+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
18+
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
19+
interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
20+
21+
22+
### Goals
23+
24+
* To instruct authorization middlewares on how to determine if a request has
25+
been authenticated by a Stack authentication middleware.
26+
* To instruct authorization middlewares on how to respond in the event that
27+
authorization fails when a request is authenticated.
28+
* To instruct authorization middlewares on how to respond in the event that
29+
authorization fails when a request is not authenticated.
30+
31+
32+
### Stack Authorization Middlewares
33+
34+
#### Token
35+
36+
Authorization should be based on the token stored in the
37+
`stack.authentication.token` request attribute. This token should be a string
38+
that can be used to gather additional information about the authenticated user
39+
making the request.
40+
41+
#### Integration with Stack Authentication
42+
43+
If authentication is provided by way of `stack.authentication.token` but the
44+
request is not authorized, a Stack authorization middleware MUST return a `403`
45+
response.
46+
47+
If authentication is not provided by way of `stack.authentication.token`, a
48+
Stack authorization middleware SHOULD return a `401` response with a
49+
`WWW-Authenticate: Stack` header. This will give the appropriate Stack
50+
authentication middlewares an opportunity to challenge as appropriate.
51+
52+
53+
### Implementations
54+
55+
* None

0 commit comments

Comments
 (0)