readme.md

Cotton is a RESTful web framework written by Go (Golang). It's fast and scalable.

Contents

• Contents
  • Installation
  • Quick start
  • Feature
  • API Example
    • Using GET, POST, PUT, OPTIONS, DELETE, PATCH, HEAD
    • Parameters in path
    • Querystring parameters
    • Using middleware
    • Using group
    • Custom NotFound
    • Custom group NotFound
    • Custom static file
    • Use template
    • PostForm
  • Benchmarks
  • Author
  • Acknowledgements

Installation

To install Cotton package, you need to install Go and set your Go workspace first.

1. The first need Go installed (go 1.13 or later)
2. install Cotton

go get -u github.com/tonny-zhang/cotton

3. Import it in your code:

import "github.com/tonny-zhang/cotton

Quick start

You can find more in example/*

package main

import "github.com/tonny-zhang/cotton"

func main() {
	r := cotton.NewRouter()
	r.Get("/hello", func(ctx *cotton.Context) {
		ctx.String("hello world from cotton")
	})

	r.Run(":8080")
}

Feature

• Fast - see Benchmarks
• parameters path
• middleware
  • session
• router group
• custom not found
• custom group not found
• custom static file
• template support
• post form
• domain

API Example

You can find a number of ready-to-run examples at examples project

Using GET, POST, PUT, OPTIONS, DELETE, PATCH, HEAD

func main() {
	r := cotton.NewRouter()
	r.Get("/hello", handler)
	r.Post("/hello", handler)

	r.Run(":8080")
}

Parameters in path

func main() {
	r := cotton.NewRouter()
	// /user/tonny		=> 	match
	// /user/123 		=> 	match
	// /user			=> 	no
	// /user/			=> 	no
	r.Get("/user/:name", func(c *cotton.Context) {
		c.String(200, "hello "+c.Param("name"))
	})

	// /file/test		=> 	match
	// /file/a/b/c		=> 	match
	// /room/			=> 	no
	r.Get("/file/*file", func(c *cotton.Context) {
		c.String(200, "file = "+c.Param("file"))
	})

	r.Run(":8080")
}

Querystring parameters

func main() {
	r := cotton.NewRouter()
	r.Get("/get", func(ctx *cotton.Context) {
		name := ctx.GetQuery("name")
		first := ctx.GetDefaultQuery("first", "first default value")

		ids := ctx.GetQueryArray("ids[]")
		m, _ := ctx.GetQueryMap("info")
		ctx.String(http.StatusOK, fmt.Sprintf("name = %s, first = %s, ids = %v, info = %v", name, first, ids, m))
	})

	r.Run("")
}

Using middleware

func main() {
	r := cotton.NewRouter()

	r.Use(cotton.Recover())
	r.Use(cotton.Logger())

	r.Get("/hello", func(c *cotton.Context) {
		c.String(200, "hello")
	})
	r.Run(":8080")
}

Using group

func main() {
	r := cotton.NewRouter()
	g1 := r.Group("/v1", func(ctx *cotton.Context) {
		// use as a middleware in group
	})
	g1.Use(func(ctx *cotton.Context) {
		fmt.Println("g1 middleware 2")
	})
	{
		g1.Get("/a", func(ctx *cotton.Context) {
			ctx.String(200, http.StatusOK, "g1 a")
		})
	}

	r.Get("/v2/a", func(ctx *cotton.Context) {
		ctx.String(200, http.StatusOK, "hello v2/a")
	})

	r.Run(":8080")
}

Custom NotFound

func main() {
	r := cotton.NewRouter()
	r.NotFound(func(ctx *cotton.Context) {
		ctx.String(http.StatusNotFound, "page ["+ctx.Request.RequestURI+"] not found")
	})

	r.Run(":8080")
}

Custom group NotFound

func main() {
	r := cotton.NewRouter()
	r.NotFound(func(ctx *cotton.Context) {
		ctx.String(http.StatusNotFound, "page ["+ctx.Request.RequestURI+"] not found")
	})
	g1 := r.Group("/v1/", func(ctx *cotton.Context) {
		fmt.Println("g1 middleware")
	})
	g1.NotFound(func(ctx *cotton.Context) {
		ctx.String(http.StatusNotFound, "group page ["+ctx.Request.RequestURI+"] not found")
	})
	r.Run(":8080")
}

Custom static file

func main() {
	dir, _ := os.Getwd()
	r := cotton.NewRouter()

	r.Use(cotton.Logger())
	// use custom static file
	r.Get("/v1/*file", func(ctx *cotton.Context) {
		file := filepath.Join(dir, ctx.Param("file"))

		http.ServeFile(ctx.Response, ctx.Request, file)
	})

	// use router.StaticFile
	r.StaticFile("/s/", dir, true)  // list dir
	r.StaticFile("/m/", dir, false) // 403 on list dir

	g := r.Group("/g/", func(ctx *cotton.Context) {
		fmt.Printf("status = %d param = %s, abspath = %s\n", ctx.Response.GetStatusCode(), ctx.Param("filepath"), filepath.Join(dir, ctx.Param("filepath")))
	})
	g.StaticFile("/", dir, true)

	r.Run("")
}

Use template

use router.LoadTemplates and ctx.Render; go to example/template for detail

PostForm

use method

• ctx.GetPostForm
• ctx.GetPostFormArray
• ctx.GetPostFormMap
• ctx.GetPostFormFile
• ctx.GetPostFormArray
• ctx.SavePostFormFile

go to example/post/ for detail

Benchmarks

the benchmarks code for cotton be found in the cotton-bench repository, so performance of cotton is good!

   cottonRouter:     90888 bytes
 BeegoMuxRouter:    107952 bytes
     BoneRouter:    100712 bytes
      ChiRouter:     75600 bytes
     HttpRouter:     36016 bytes
       trie-mux:    131568 bytes
      GoRouter1:     83112 bytes
goos: darwin
goarch: amd64
pkg: cottonbench
cpu: Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz
BenchmarkHttpRouterWithGithubAPI-8                 38082             31611 ns/op    13856 B/op        169 allocs/op
BenchmarkCottonRouterWithGithubAPI-8               34648             35496 ns/op        0 B/op          0 allocs/op
BenchmarkBeegoMuxRouterWithGithubAPI-8              9888            120716 ns/op   139056 B/op       1050 allocs/op
BenchmarkBoneRouterWithGithubAPI-8                   640           1869374 ns/op   744018 B/op       8893 allocs/op
BenchmarkTrieMuxRouterWithGithubAPI-8              17448             68756 ns/op    66624 B/op        543 allocs/op
BenchmarkGoRouter1WithGithubAPI-8                     60          18084650 ns/op 14432841 B/op     132968 allocs/op

Author

• tonny zhang

Acknowledgements

This package is inspired by the following

• httprouter
• gin