Skip to content
This repository was archived by the owner on Feb 7, 2018. It is now read-only.

Commit 70e6ec2

Browse files
author
Arthur White
committed
New doc style
1 parent 9967277 commit 70e6ec2

File tree

6 files changed

+60
-205
lines changed

6 files changed

+60
-205
lines changed

‎README.md

+3-108
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,5 @@
1-
<p align="center"><img src="http://volatile.whitedevops.com/images/repositories/core/logo.png" alt="Volatile Core" title="Volatile Core"><br><br></p>
1+
<p align="center"><a href="https://godoc.org/github.com/volatile/core"><img src="http://volatile.whitedevops.com/images/repositories/core/logo.png" alt="core" title="core"></a><br><br></p>
22

3-
Volatile Core is the perfect foundation for any web app as it's designed to have the best balance between **readability**, **flexibility** and **performance**.
3+
Package core provides a pure handlers (or middlewares) stack so you can perform actions downstream, then filter and manipulate the response upstream.
44

5-
It provides a pure handlers (or *middlewares*) stack so you can perform actions downstream, then filter and manipulate the response upstream.
6-
7-
No handlers or helpers are bundled in the Core: it does one thing and does it well.
8-
You can find [official packages](#official-handlers) below.
9-
10-
For a complete **documentation**, see the [Volatile website](http://volatile.whitedevops.com).
11-
You can also read all the code (~100 LOC) within minutes.
12-
13-
## Installation
14-
15-
```Shell
16-
$ go get github.com/volatile/core
17-
```
18-
19-
## Usage [![GoDoc](https://godoc.org/github.com/volatile/core?status.svg)](https://godoc.org/github.com/volatile/core)
20-
21-
```Go
22-
package main
23-
24-
import (
25-
"fmt"
26-
"log"
27-
"time"
28-
29-
"github.com/volatile/core"
30-
)
31-
32-
func main() {
33-
// Log
34-
core.Use(func(c *core.Context) {
35-
start := time.Now()
36-
c.Next()
37-
log.Printf(" %s %s %s", c.Request.Method, c.Request.URL, time.Since(start))
38-
})
39-
40-
// Response
41-
core.Use(func(c *core.Context) {
42-
fmt.Fprint(c.ResponseWriter, "Hello, World!")
43-
})
44-
45-
core.Run()
46-
}
47-
```
48-
49-
By default, your app is reachable at [localhost:8080](http://localhost:8080).
50-
51-
### Flags
52-
53-
These flags are preset:
54-
55-
- `-address` to set a custom listening address.
56-
The value is saved in [`Address`](https://godoc.org/github.com/volatile/core#Address).
57-
58-
- `-production` to switch on production environment settings.
59-
Some third-party handlers may have different behaviors depending on the environment.
60-
The value is saved in [`Production`](https://godoc.org/github.com/volatile/core#Production).
61-
62-
It's up to you to call [`flag.Parse()`](https://golang.org/pkg/flag/#Parse) in your main function if you want to use them.
63-
64-
### Panic recovering
65-
66-
Volatile Core recovers your server from any panic, logs the error with stack, and sends a `500 Internal Server Error`.
67-
If you want to use a custom handler on panic, give one to [`HandlePanic`](https://godoc.org/github.com/volatile/core#HandlePanic).
68-
69-
### Compatibility
70-
71-
Volatile Core is fully compatible with the [`net/http.Handler`](https://golang.org/pkg/net/http/#Handler) interface. Use [`NewHandlersStack`](https://godoc.org/github.com/volatile/core#NewHandlersStack):
72-
73-
```Go
74-
package main
75-
76-
import (
77-
"fmt"
78-
"net/http"
79-
80-
"github.com/volatile/core"
81-
)
82-
83-
func main() {
84-
hs := core.NewHandlersStack()
85-
86-
hs.Use(func(c *core.Context) {
87-
fmt.Fprint(c.ResponseWriter, "Hello, World!")
88-
})
89-
90-
http.ListenAndServe(":8080", hs)
91-
}
92-
```
93-
94-
## Official handlers
95-
96-
These handlers are ready to be integrated in any of your app:
97-
98-
- [Compress](https://github.com/volatile/compress) — Clever response compressing
99-
- [CORS](https://github.com/volatile/cors) — Cross-Origin Resource Sharing support
100-
- [Log](https://github.com/volatile/log) — Requests logging
101-
- [Secure](https://github.com/volatile/secure) — Quick security wins
102-
- [Static](https://github.com/volatile/static) — Simple assets serving
103-
104-
## Official helpers
105-
106-
These helpers provide syntactic sugar to ease repetitive code:
107-
108-
- [I18n](https://github.com/volatile/i18n) — Simple internationalization
109-
- [Response](https://github.com/volatile/response) — Readable response helper
110-
- [Route](https://github.com/volatile/route) — Flexible routing helper
5+
[![GoDoc](https://godoc.org/github.com/volatile/core?status.svg)](https://godoc.org/github.com/volatile/core)

‎doc.go

+55-89
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,81 @@
11
/*
2-
Package core is the perfect foundation for any web app as it's designed to have the best balance between readability, flexibility and performance.
2+
Package core provides a pure handlers (or middlewares) stack so you can perform actions downstream, then filter and manipulate the response upstream.
33
4-
It provides a pure handlers (or "middlewares") stack so you can perform actions downstream, then filter and manipulate the response upstream.
4+
The handlers stack
55
6-
No handlers or helpers are bundled in the Core: it does one thing and does it well.
7-
You can find official packages below.
8-
9-
For a complete documentation, see the Volatile website (http://volatile.whitedevops.com).
10-
You can also read all the code (~100 LOC) within minutes.
11-
12-
Installation
13-
14-
In the terminal:
15-
16-
$ go get github.com/volatile/core
17-
18-
Usage
6+
A handler is a function that receives a context.
7+
It can be registered with Use and has the possibility to break the sream or to continue with the next handler in the stack.
198
209
Example of a logger followed by the response writing:
2110
22-
package main
11+
// Log
12+
core.Use(func(c *core.Context) {
13+
start := time.Now()
14+
c.Next()
15+
log.Printf(" %s %s %s", c.Request.Method, c.Request.URL, time.Since(start))
16+
})
17+
18+
// Response
19+
core.Use(func(c *core.Context) {
20+
fmt.Fprint(c.ResponseWriter, "Hello, World!")
21+
})
2322
24-
import (
25-
"fmt"
26-
"log"
27-
"time"
23+
// Run server
24+
core.Run()
2825
29-
"github.com/volatile/core"
30-
)
26+
When using Run, your app is reachable at http://localhost:8080 by default.
3127
32-
func main() {
33-
// Log
34-
core.Use(func(c *core.Context) {
35-
start := time.Now()
36-
c.Next()
37-
log.Printf(" %s %s %s", c.Request.Method, c.Request.URL, time.Since(start))
38-
})
28+
If you need more flexibility, you can make a new handlers stack, which is fully compatible with the net/http.Handler interface:
3929
40-
// Response
41-
core.Use(func(c *core.Context) {
42-
fmt.Fprint(c.ResponseWriter, "Hello, World!")
43-
})
30+
hs := core.NewHandlersStack()
4431
45-
core.Run()
46-
}
32+
hs.Use(func(c *core.Context) {
33+
fmt.Fprint(c.ResponseWriter, "Hello, World!")
34+
})
4735
48-
By default, your app is reachable at http://localhost:8080.
36+
http.ListenAndServe(":8080", hs)
4937
5038
Flags
5139
5240
These flags are preset:
5341
54-
● -address to set a custom listening address.
55-
The value is saved in Address.
42+
-address The address to listen and serving on.
43+
Value is saved in Address.
44+
-production Run the server in production environment.
45+
Some third-party handlers may have different behaviors depending on the environment.
46+
Value is saved in Production.
47+
48+
It's up to you to call
5649
57-
● -production to switch on production environment settings.
58-
Some third-party handlers may have different behaviors depending on the environment.
59-
The value is saved in Production.
50+
flag.Parse()
6051
61-
It's up to you to call flag.Parse() in your main function if you want to use them.
52+
in your main function if you want to use them.
6253
6354
Panic recovering
6455
65-
Volatile Core recovers your server from any panic, logs the error with stack, and sends a 500 Internal Server Error.
56+
When using Run, your server always recovers from panics, logs the error with stack, and sends a 500 Internal Server Error.
6657
If you want to use a custom handler on panic, give one to HandlePanic.
6758
68-
Compatibility
69-
70-
Volatile Core is fully compatible with the net/http.Handler interface. Just use NewHandlersStack:
71-
72-
package main
73-
74-
import (
75-
"fmt"
76-
"net/http"
77-
78-
"github.com/volatile/core"
79-
)
80-
81-
func main() {
82-
hs := core.NewHandlersStack()
83-
84-
hs.Use(func(c *core.Context) {
85-
fmt.Fprint(c.ResponseWriter, "Hello, World!")
86-
})
87-
88-
http.ListenAndServe(":8080", hs)
89-
}
90-
91-
Official handlers
92-
93-
These handlers are ready to be integrated in any of your app:
94-
95-
● Compress — Clever response compressing — https://github.com/volatile/compress
96-
97-
● CORS — Cross-Origin Resource Sharing support — https://github.com/volatile/cors
98-
99-
● Log — Requests logging — https://github.com/volatile/log
100-
101-
● Secure — Quick security wins — https://github.com/volatile/secure
102-
103-
● Static — Simple assets serving — https://github.com/volatile/static
104-
105-
Official helpers
106-
107-
These helpers provide syntactic sugar to ease repetitive code:
108-
109-
● I18n — Simple internationalization — https://github.com/volatile/i18n
110-
111-
● Response — Readable response helper — https://github.com/volatile/response
112-
113-
● Route — Flexible routing helper — https://github.com/volatile/route
59+
Handlers & Helpers
60+
61+
No handlers or helpers are bundled in the core: it does one thing and does it well.
62+
That's why you need to import all and only the handlers or helpers you need:
63+
64+
compress Clever response compressing
65+
https://godoc.org/github.com/volatile/compress
66+
cors Cross-Origin Resource Sharing support
67+
https://godoc.org/github.com/volatile/cors
68+
i18n Simple internationalization
69+
https://godoc.org/github.com/volatile/i18n
70+
log Requests logging
71+
https://godoc.org/github.com/volatile/log
72+
response Readable response helper
73+
https://godoc.org/github.com/volatile/response
74+
route Flexible routing helper
75+
https://godoc.org/github.com/volatile/route
76+
secure Quick security wins
77+
https://godoc.org/github.com/volatile/secure
78+
static Simple assets serving
79+
https://godoc.org/github.com/volatile/static
11480
*/
11581
package core

‎httputil/doc.go

-4
This file was deleted.

‎httputil/response.go

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Package httputil provides HTTP utility functions, complementing the most common ones in the net/http package.
12
package httputil
23

34
import (

‎log/doc.go

-4
This file was deleted.

‎log/log.go

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Package log implements a simple logging package for handlers usage.
12
package log
23

34
import (

0 commit comments

Comments
 (0)