Core services

    Every handler invocation comes with its own request context, which is represented as the type flamego.Contextopen in new window. Data and state are not shared among these request contexts, which makes handler invocations independent from each other unless your web application has defined some other shared resources (e.g. database connections, cache).

    Thereforce, flamego.Context is available to use out-of-the-box by your handlers:

    When a route is matched by a request, the Flame instance (including middleware) to be invoked in the same order as they are registered.

    By default, the next handler will only be invoked after the previous one in the chain has finished. You may change this behvaior using the Next method, which allows you to pause the execution of the current handler and resume after the rest of the chain finished.

    1. package main
    3. import (
    4.     "fmt"
    6.     "github.com/flamego/flamego"
    7. )
    9. func main() {
    10.     f := flamego.New()
    11.     f.Get("/",
    12.         func(c flamego.Context) {
    13.             fmt.Println("starting the first handler")
    14.             c.Next()
    15.             fmt.Println("exiting the first handler")
    16.         },
    17.         func() {
    18.             fmt.Println("executing the second handler")
    19.         },
    20.     )
    21.     f.Run()
    22. }

    When you run the above program and do curl http://localhost:2830/, the following logs are printed to your terminal:

    1. [Flamego] Listening on 0.0.0.0:2830 (development)
    2. starting the first handler
    3. executing the second handler
    4. exiting the first handler

    The routing logger is taking advantage of this feature to .

    Remote address

    Web applications often want to know where clients are coming from, then the RemoteAddr() method is the convenient helper made for you:

    1. func main() {
    2.     f := flamego.New()
    3.     f.Get("/", func(c flamego.Context) string {
    4.         return "The remote address is " + c.RemoteAddr()
    5.     })
    6.     f.Run()
    7. }

    The RemoteAddr() method is smarter than the standard library that only looks at the http.Request.RemoteAddr field (which stops working if your web application is behind a reverse proxy), it also takes into consideration of some well-known headers.

    This method looks at following things in the order to determine which one is more likely to contain the real client address:

    • The X-Real-IP request header
    • The X-Forwarded-For request header
    • The http.Request.RemoteAddr field

    This way, you can configure your reverse proxy to pass on one of these headers.

    WARNING

    The client can always fake its address using a proxy or VPN, getting the remote address is always considered as a best effort in web applications.

    The Redirect method is given the fact that the request context knows what the http.ResponseWriter and *http.Request are for the current request, and uses the http.StatusFound as the default status code for the redirection:

    • Code
    • Test
    1. package main
    3. import (
    4.     "net/http"
    6.     "github.com/flamego/flamego"
    7. )
    9. func main() {
    10.     f := flamego.New()
    11.     f.Get("/", func(c flamego.Context) {
    12.         c.Redirect("/signup")
    13.     })
    14.     f.Get("/login", func(c flamego.Context) {
    15.         c.Redirect("/signin", http.StatusMovedPermanently)
    16.     })
    17.     f.Run()
    18. }
    1. $ curl -i http://localhost:2830/
    2. HTTP/1.1 302 Found
    3. ...
    5. $ curl -i http://localhost:2830/login
    6. HTTP/1.1 301 Moved Permanently
    7. ...

    WARNING

    Be aware that the Redirect method does a naive redirection and is vulnerable to the open redirect vulnerabilityopen in new window.

    For example, the following is also works as a valid redirection:

    1. c.Redirect("https://www.google.com")

    Please make sure to always first validating the user input!

    URL parameters

    URL parametersCore services - 图6open in new window, also known as “URL query parameters”, or “URL query strings”, are commonly used to pass arguments to the backend for all HTTP methods (POST forms have to be sent with POST method, as the counterpart).

    The Query method is built as a helper for accessing the URL parameters, and return an empty string if no such parameter found with the given key:

    • Code
    • Test
    1. package main
    3. import (
    4.     "github.com/flamego/flamego"
    5. )
    7. func main() {
    8.     f := flamego.New()
    9.     f.Get("/", func(c flamego.Context) string {
    10.         return "The name is " + c.Query("name")
    11.     })
    12.     f.Run()
    13. }
    1. $ curl http://localhost:2830?name=joe
    2. The name is joe
    4. $ curl http://localhost:2830

    There is a family of Query methods available at your fingertips, including:

    • QueryTrim trims spaces and returns value.
    • QueryStrings returns a list of strings.
    • QueryUnescape returns unescaped query result.
    • QueryBool returns value parsed as bool.
    • QueryInt returns value parsed as int.
    • QueryInt returns value parsed as int64.
    • QueryFloat64 returns value parsed as float64.

    TIP

    1. vals := c.Request().URL.Query()

    No.

    The flamego.Context is a representation of the request context and should live within the routing layer, where the is a general purpose context and can be propogated to almost anywhere (e.g. database layer).

    You can retrieve the context.Context of a request using the following methods:

    1. f.Get(..., func(c flamego.Context) {
    2.     ctx := c.Request().Context()
    3.     ...
    4. })
    6. // or
    8. f.Get(..., func(r *http.Request) {
    9.     ctx := r.Context()
    10.     ...
    11. })

    Default logger

    The *log.Loggeropen in new window is available to all handers for general logging purposes, this is particularly useful if you’re writing middleware:

    When you run the above program and do curl http://localhost:2830/, the following logs are printed to your terminal:

    1. [Flamego] Listening on 0.0.0.0:2830 (development)
    2. [Flamego] Hello, Flamego!

    The is taking advantage of this feature to print the duration and status code of requestsCore services - 图9open in new window.

    The response stream of a request is represented by the type , you may use it as an argument of your handlers or through the ResponseWriter method of the flamego.Context:

    1. f.Get(..., func(w http.ResponseWriter) {
    2.     ...
    3. })
    5. // or
    7. f.Get(..., func(c flamego.Context) {
    8.     w := c.ResponseWriter()
    9.     ...
    10. })

    💡 小贴士

    Not all handlers that are registered for a route are always being invoked, the request context (flamego.Context) stops invoking subsequent handlers when the response status code has been writtenCore services - 图11open in new window by the current handler. This is similar to how the works.

    Request object

    The request object is represented by the type , you may use it as an argument of your handlers or through the Request().Request field of the flamego.Context:

    1. f.Get(..., func(r *http.Request) {
    2.     ...
    3. })
    5. // or
    7. f.Get(..., func(c flamego.Context) {
    8.     r := c.Request().Request
    9.     ...
    10. })

    You may wonder what does c.Request() return in the above example?

    Good catch! It returns a thin wrapper of the *http.Request and has the type *flamego.Requestopen in new window, which provides helpers to read the request body:

    1. f.Get(..., func(c flamego.Context) {
    2.     body := c.Request().Body().Bytes()
    3.     ...
    4. })

    TIP

    This middleware is automatically registered when you use to create a Flame instance.

    The flamego.Loggeropen in new window is the middleware that provides logging of requested routes and corresponding status code:

    1. package main
    3. import (
    4.     "github.com/flamego/flamego"
    5. )
    7. func main() {
    8.     f := flamego.New()
    9.     f.Use(flamego.Logger())
    10.     f.Get("/", func() (int, error) {
    11.         return http.StatusOK, nil
    12.     })
    13.     f.Run()
    14. }

    When you run the above program and do curl http://localhost:2830/, the following logs are printed to your terminal:

    1. [Flamego] Listening on 0.0.0.0:2830 (development)
    2. [Flamego] ...: Started GET / for 127.0.0.1
    3. [Flamego] ...: Completed GET / 200 OK in 165.791µs

    Panic recovery

    TIP

    This middleware is automatically registered when you use flamego.ClassicCore services - 图17open in new window to create a Flame instance.

    The is the middleware that is for recovering from panic:

    1. package main
    3. import (
    4.     "github.com/flamego/flamego"
    5. )
    7. func main() {
    8.     f := flamego.New()
    9.     f.Use(flamego.Recovery())
    10.     f.Get("/", func() {
    11.         panic("I can't breath")
    12.     })
    13.     f.Run()
    14. }

    When you run the above program and visit http://localhost:2830/Core services - 图19open in new window, the recovered page is displayed:

    This middleware is automatically registered when you use to create a Flame instance.

    The flamego.Staticopen in new window is the middleware that is for serving static files, and it accepts an optional :

    1. func main() {
    2.     f := flamego.New()
    3.     f.Use(flamego.Static(
    4.         flamego.StaticOptions{
    5.             Directory: "public",
    6.         },
    7.     ))
    8.     f.Run()
    9. }

    You may also omit passing the options for using all default values:

    1. func main() {
    2.     f := flamego.New()
    3.     f.Use(flamego.Static())
    4.     f.Run()
    5. }

    Example: Serving the source file

    In this example, we’re going to treat our source code file as the static resources:

    1. package main
    3. import (
    4.     "github.com/flamego/flamego"
    5. )
    7. func main() {
    9.     f.Use(flamego.Static(
    10.             Directory: "./",
    11.             Index:     "main.go",
    12.         },
    13.     ))
    14.     f.Run()
    15. }

    On line 11, we changed the Directory to be the working directory ("./") instead of the default value "public".

    On line 12, we changed the index file (the file to be served when listing a directory) to be main.go instead of the default value "index.html".

    When you save the above program as main.go and run it, both curl http://localhost:2830/ and curl http://localhost:2830/main.go will response the content of this main.go back to you.

    In this example, we’re going to serve static resources for two different directories.

    Here is the setup for the example:

    • Directory
    • css/main.css
    • js/main.js
    • main.go
    • Test
    1. html {
    2.     color: red;
    3. }
    1. console.log("Hello, Flamego!");
    1. package main
    3. import (
    4.     "github.com/flamego/flamego"
    5. )
    7. func main() {
    8.     f := flamego.New()
    9.     f.Use(flamego.Static(
    10.         flamego.StaticOptions{
    11.             Directory: "js",
    12.         },
    13.     ))
    14.     f.Use(flamego.Static(
    15.         flamego.StaticOptions{
    16.             Directory: "css",
    17.         },
    18.     ))
    19.     f.Run()
    20. }
    1. $ curl http://localhost:2830/main.css
    2. html {
    3.     color: red;
    4. }
    6. $ curl http://localhost:2830/main.js
    7. console.log("Hello, Flamego!");

    You may have noticed that the client should not include the value of Directory, which are "css" and "js" in the example. If you would like the client to include these values, you can use the Prefix option:

    1. f.Use(flamego.Static(
    2.     flamego.StaticOptions{
    3.         Directory: "css",
    4.         Prefix:    "css",
    5.     },
    6. ))

    💡 小贴士

    The value of Prefix does not have to be the same as the value of Directory.

    Example: Serving the embed.FS

    In this example, we’re going to serve static resources from the embed.FSopen in new window that was .

    Here is the setup for the example:

    • Directory
    • css/main.css
    • main.go
    • Test
    1. tree .
    2. .
    3. ├── css
    4. │   └── main.css
    5. ├── go.mod
    6. ├── go.sum
    7. └── main.go
    1. html {
    2.     color: red;
    3. }
    1. package main
    3. import (
    4.     "embed"
    5.     "net/http"
    7.     "github.com/flamego/flamego"
    8. )
    10. //go:embed css
    11. var css embed.FS
    13. func main() {
    14.     f := flamego.New()
    15.     f.Use(flamego.Static(
    16.         flamego.StaticOptions{
    17.             FileSystem: http.FS(css),
    18.         },
    19.     ))
    20.     f.Run()
    21. }
    1. $ curl http://localhost:2830/css/main.css
    2. html {
    3.     color: red;
    4. }

    WARNING

    Because the Go embed encodes the entire path (i.e. including parent directories), the client have to use the full path, which is different from serving static files directly from the local disk.

    In other words, the following command will not work for the example:

    1. $ curl http://localhost:2830/main.css
    2. 404 page not found

    Rendering content

    The is a minimal middleware that is for rendering content, and it accepts an optional flamego.RenderOptionsCore services - 图27open in new window.

    The service is injected to your request context and you can use it to render JSON, XML, binary and plain text content:

    • Code
    • Test
    1. $ curl -i http://localhost:2830/
    2. HTTP/1.1 200 OK
    3. Content-Type: application/json; charset=utf-8
    4. ...
    6. {
    7.   "id": 1,
    8.   "username": "joe"

    TIP

    Try changing the line 13 to JSONIndent: "",, then redo all test requests and see what changes.