diff --git a/Cookies.md b/Cookies.md new file mode 100644 index 0000000..d3ee2cd --- /dev/null +++ b/Cookies.md @@ -0,0 +1,135 @@ +Cookies are accessible through the Request instance of Context. The `ctx.Request()` returns a `net/http#Request`. + +However the Iris `Context` provides some helpers to make the most common use cases of cookies easier accessible to you and without any custom additional code of yours that would be required if you just using the Request's Cookies methods. + +## Set a Cookie + +The `SetCookie` method adds a cookie. + +Use of the "options" is not required, they can be used to modify the "cookie". You'll see later on what the available options are, custom ones can be added depending on your web application requirements, this also helps to not repeat yourself in a codebase. + +```go +SetCookie(cookie *http.Cookie, options ...CookieOption) +``` + +If you want you can also use the `SetCookieKV` method which does not require an import of the `net/http` package. + +```go +SetCookieKV(name, value string, options ...CookieOption) +``` + +Note that the default expiration for a cookie set by `SetCookieKV` is 365 days. You can either use the `CookieExpires` Cookie Option(see below) or globally by setting the `kataras/iris/Context.SetCookieKVExpiration` package-level variable. + +The `CookieOption` is just a type for `func(*http.Cookie)`. + +**Set Path** + +```go +CookiePath(path string) CookieOption +``` + +**Set Expiration** + +```go +iris.CookieExpires(durFromNow time.Duration) CookieOption +``` + +**HttpOnly** + +```go +iris.CookieHTTPOnly(httpOnly bool) CookieOption +``` + +> HttpOnly field defaults to true for `RemoveCookie` and `SetCookieKV`. + + +And let's go a bit further with cookie encoding. + +**Encode** + +Provides encoding functionality when adding a cookie. + +Accepts a `CookieEncoder` and sets the cookie's value to the encoded value. + +Users of that is the `SetCookie` and `SetCookieKV`. + +```go +iris.CookieEncode(encode CookieEncoder) CookieOption +``` + +**Decode** + +Provides decoding functionality when retrieving a cookie. + +Accepts a `CookieDecoder` and sets the cookie's value to the decoded value before return by the `GetCookie`. + +User of that is the `GetCookie`. + +```go +iris.CookieDecode(decode CookieDecoder) CookieOption +``` + +Where `CookieEncoder` can be described as: + +A CookieEncoder should encode the cookie value. + +* Should accept the cookie's name as its first argument and +* as second argument the cookie value ptr. +* Should return an encoded value or an empty one if encode operation failed. +* Should return an error if encode operation failed. + +```go +CookieEncoder func(cookieName string, value interface{}) (string, error) +``` + +And `CookieDecoder`: + +CookieDecoder should decode the cookie value. + +* Should accept the cookie's name as its first argument, +* as second argument the encoded cookie value and as third argument the decoded value ptr. +* Should return a decoded value or an empty one if decode operation failed. +* Should return an error if decode operation failed. + +```go +CookieDecoder func(cookieName string, cookieValue string, v interface{}) error +``` + +Errors are not printed, so you have to know what you're doing, +and remember: if you use AES it only supports key sizes of 16, 24 or 32 bytes. + +You either need to provide exactly that amount or you derive the key from what you type in. + +## Get a Cookie + +The `GetCookie` returns cookie's value by its name, returns empty string if nothing was found. + +```go +GetCookie(name string, options ...CookieOption) string +``` + +If you want more than the value then use the following instead: + +```go +cookie, err := ctx.Request().Cookie("name") +``` + +## Get all Cookies + +The `ctx.Request().Cookies()` method returns a slice of all the available request cookies. Sometimes you want to modify them or perform an action on each one of them, the easiet way to do that is by the `VisitAllCookies` method. + +```go +VisitAllCookies(visitor func(name string, value string)) +``` + +## Remove a Cookie + +The `RemoveCookie` method deletes a cookie by its name and path = "/", the root one. + +Tip: change the cookie's path to the current one by providing the `iris.CookieCleanPath` Cookie Options, as : `RemoveCookie("nname", iris.CookieCleanPath)`. + +Also, note that the default behavior is to set its `HttpOnly` to true. It performs a removal of cookie based on the web standards. + +```go +RemoveCookie(name string, options ...CookieOption) +``` diff --git a/Home.md b/Home.md index 6ab115b..11053f6 100644 --- a/Home.md +++ b/Home.md @@ -8,6 +8,7 @@ This wiki is the main source of documentation for **developers** working with (o * [[Support]] * [[Installing Iris|Installation]] * [[Getting Started]] +* [[Host]] * [[Routing]] * [[Path Parameter Types|Routing-path-parameter-types]] * [[Reverse Lookups|Routing-reverse-lookups]] @@ -15,6 +16,7 @@ This wiki is the main source of documentation for **developers** working with (o * [[Handle HTTP errors|Routing-error-handlers]] * [[Wrap the Router|Routing-wrap-the-router]] * [[Dependency Injection|Routing-dependency-injection]] +* [[Cookies]] ## Runnable Examples diff --git a/Host.md b/Host.md new file mode 100644 index 0000000..5d7eb46 --- /dev/null +++ b/Host.md @@ -0,0 +1,249 @@ +## Listen and Serve + +You can start the server(s) listening to any type of `net.Listener` or even `http.Server` instance. +The method for initialization of the server should be passed at the end, via `Run` function. + +The most common method that Go developers are use to serve their servers are +by passing a network address with form of "hostname:ip". With Iris +we use the `iris.Addr` which is an `iris.Runner` type + +```go +// Listening on tcp with network address 0.0.0.0:8080 +app.Run(iris.Addr(":8080")) +``` + +Sometimes you have created a standard net/http server somewhere else in your app and want to use that to serve the Iris web app + +```go +// Same as before but using a custom http.Server which may being used somewhere else too +app.Run(iris.Server(&http.Server{Addr:":8080"})) +``` + +The most advanced usage is to create a custom or a standard `net.Listener` and pass that to `app.Run` + +```go +// Using a custom net.Listener +l, err := net.Listen("tcp4", ":8080") +if err != nil { + panic(err) +} +app.Run(iris.Listener(l)) +``` + +A more complete example, using the unix-only socket files feature + +```go +package main + +import ( + "os" + "net" + + "github.com/kataras/iris" +) + +func main() { + app := iris.New() + + // UNIX socket + if errOs := os.Remove(socketFile); errOs != nil && !os.IsNotExist(errOs) { + app.Logger().Fatal(errOs) + } + + l, err := net.Listen("unix", socketFile) + + if err != nil { + app.Logger().Fatal(err) + } + + if err = os.Chmod(socketFile, mode); err != nil { + app.Logger().Fatal(err) + } + + app.Run(iris.Listener(l)) +} +``` + +UNIX and BSD hosts can take advandage of the reuse port feature + +```go +package main + +import ( + // Package tcplisten provides customizable TCP net.Listener with various + // performance-related options: + // + // - SO_REUSEPORT. This option allows linear scaling server performance + // on multi-CPU servers. + // See https://www.nginx.com/blog/socket-sharding-nginx-release-1-9-1/ for details. + // + // - TCP_DEFER_ACCEPT. This option expects the server reads from the accepted + // connection before writing to them. + // + // - TCP_FASTOPEN. See https://lwn.net/Articles/508865/ for details. + "github.com/valyala/tcplisten" + + "github.com/kataras/iris" +) + +// go get github.com/valyala/tcplisten +// go run main.go + +func main() { + app := iris.New() + + app.Get("/", func(ctx iris.Context) { + ctx.HTML("