Introduction

HTTP method override is a technique used to support clients that do not support certain HTTP methods such as PUT or DELETE. This is particularly useful for web browsers and older clients that only support GET and POST methods. The Iris web framework provides a robust and flexible method override middleware that allows developers to easily implement HTTP method overriding in their applications. This guide will walk you through the features and usage of the Iris method override middleware, helping you to understand and leverage its capabilities to enhance your web applications.

Features of Iris Method Override Middleware

The Iris method override middleware offers a variety of features to handle HTTP method overriding efficiently. These features include:

1. Customizable Methods: Define which HTTP methods can be overridden.
2. Custom Headers: Specify custom headers to determine the method override.
3. Form Field Support: Use form fields to specify the method override.
4. Query Parameter Support: Use query parameters to specify the method override.
5. Save Original Method: Optionally save the original HTTP method for later use.

Installation

To use the Iris method override middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v12/middleware/methodoverride"

Usage

Basic Setup

To use the method override middleware, you need to import the necessary packages and configure the middleware in your Iris application. Here is a basic example:

package main

import (
 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/methodoverride"
)

func main() {
 app := iris.New()

 // Create the method override middleware
 mo := methodoverride.New(
  methodoverride.SaveOriginalMethod("_originalMethod"),
 )

 // Register the middleware with UseRouter
 app.UseRouter(mo)

 app.Post("/path", func(ctx iris.Context) {
  ctx.WriteString("POST response")
 })

 app.Delete("/path", func(ctx iris.Context) {
  ctx.WriteString("DELETE response")
 })

 app.Listen(":8080")
}

Customizable Methods

You can define which HTTP methods can be overridden using the Methods option. By default, only the POST method can be overridden. Here is an example:

mo := methodoverride.New(
    methodoverride.Methods("POST", "PUT"),
)

Custom Headers

You can specify custom headers to determine the method override using the Headersoption. By default, the middleware checks the following headers: X-HTTP-Method, X-HTTP-Method-Override, and X-Method-Override. Here is an example:

mo := methodoverride.New(
    methodoverride.Headers("X-Custom-Method"),
)

Form Field Support

You can use form fields to specify the method override using the FormFieldoption. By default, the middleware checks the _method form field. Here is an example:

mo := methodoverride.New(
    methodoverride.FormField("_method"),
)

Query Parameter Support

You can use query parameters to specify the method override using the Queryoption. By default, the middleware checks the _method query parameter. Here is an example:

mo := methodoverride.New(
    methodoverride.Query("_method"),
)

Save Original Method

You can optionally save the original HTTP method for later use using the SaveOriginalMethod option. Here is an example:

mo := methodoverride.New(
    methodoverride.SaveOriginalMethod("_originalMethod"),
)

Example

Here is a complete example demonstrating how to use the method override middleware with an Iris application:

package main

import (
 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/methodoverride"
)

func main() {
 app := iris.New()

 // Create the method override middleware
 mo := methodoverride.New(
  methodoverride.SaveOriginalMethod("_originalMethod"),
 )

 // Register the middleware with UseRouter
 app.UseRouter(mo)

 app.Post("/path", func(ctx iris.Context) {
  ctx.WriteString("POST response")
 })

 app.Delete("/path", func(ctx iris.Context) {
  ctx.WriteString("DELETE response")
 })

 app.Listen(":8080")
}

Conclusion

The Iris method override middleware provides a simple and efficient way to support clients that do not support certain HTTP methods. By leveraging the features of this middleware, you can enhance the compatibility and flexibility of your web applications.

Overview

The Iris Body Limit middleware is a powerful tool for controlling the size of incoming request bodies in your Iris web applications. By setting a limit on the size of request bodies, you can prevent clients from sending excessively large payloads that could potentially overwhelm your server or lead to denial-of-service (DoS) attacks. This middleware is particularly useful for applications that handle file uploads, JSON payloads, or any other type of data that could vary significantly in size.

Why Use Body Limit Middleware?

Security

One of the primary reasons to use body limit middleware is to enhance the security of your application. By limiting the size of incoming request bodies, you can mitigate the risk of DoS attacks, where an attacker sends large payloads to exhaust server resources.

Performance

Limiting the size of request bodies can also improve the performance of your application. Large payloads can consume significant amounts of memory and processing power, slowing down your server and affecting the user experience. By setting a reasonable limit, you can ensure that your server remains responsive and efficient.

Resource Management

In applications that handle file uploads or large JSON payloads, it’s essential to manage resources effectively. By setting a body limit, you can prevent clients from uploading excessively large files or sending huge JSON objects that could strain your server’s resources.

Installation

To use the bodylimit middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v12/middleware/bodylimit"

Usage

Basic Setup

To use the body limit middleware, you need to create an Iris application and register the middleware. Below is an example of how to set up the middleware with a limit of 2 MB:

package main

import (
 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/bodylimit"
)

func main() {
 app := iris.New()
 app.Use(bodylimit.New(2 * iris.MB)) // set the limit to 2 MB.

 handler := func(ctx iris.Context) {
  body, err := ctx.Body()
  if err != nil {
   ctx.StopWithPlainError(iris.StatusInternalServerError, err)
   return
  }

  ctx.Write(body) // write the request body back to the client.
 }

 app.Post("/", handler)
 app.Listen(":8080")
}

Explanation

• Limit: The bodylimit.New function takes a single parameter, which is the maximum size of the request body in bytes. In the example above, the limit is set to 10 bytes.
• Handler: The handler reads the request body and writes it back to the response. If the request body exceeds the limit, the middleware will stop the request and return a 413 Request Entity Too Large status.
• The body limit middleware uses a sync.Pool to manage Reader instances, which are used to read the request body and enforce the size limit. This approach ensures efficient memory usage and reduces the overhead of creating new Reader instances for each request.

Testing Handlers with BodyLimit Middleware

To test handlers that use the BodyLimit middleware, you can use the httptest package provided by Iris. Here is an example of how to test a handler:

package main_test

import (
 "testing"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/httptest"
 "github.com/kataras/iris/v12/middleware/bodylimit"
)

func TestBodyLimit(t *testing.T) {
 limit := int64(10) // set the limit to 10 bytes for the shake of the test.

 handler := func(ctx iris.Context) {
  body, err := ctx.Body()
  if err != nil {
   ctx.StopWithPlainError(iris.StatusInternalServerError, err)
   return
  }
  ctx.Write(body)
 }

 app := iris.New()
 app.Use(bodylimit.New(limit))
 app.Post("/", handler)

 e := httptest.New(t, app)

 // Test with a body that is smaller than the limit.
 e.POST("/").WithText("123456789").Expect().Status(iris.StatusOK).Body().IsEqual("123456789")

 // Test with a body that is equal to the limit.
 e.POST("/").WithText("1234567890").Expect().Status(iris.StatusOK).Body().IsEqual("1234567890")

 // Test with a body that is bigger than the limit.
 e.POST("/").WithText("12345678910").Expect().Status(iris.StatusRequestEntityTooLarge)
}

Conclusion

The Iris Body Limit middleware provides a simple yet effective way to control the size of incoming request bodies in your Iris web applications. By setting a limit on the size of request bodies, you can enhance the security, performance, and resource management of your application. With easy integration and advanced features, this middleware is a valuable tool for any Iris developer.

Overview

The Basic Authentication middleware provides a robust and flexible way to secure your Iris web applications. It supports various user storage methods, including in-memory lists, files, and databases, and offers advanced features such as password encryption, custom error handling, and session expiration.

Installation

To use the basicauth middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v12/middleware/basicauth"

Features

Authentication Function

The core of the middleware is the Allow field, which is a function with the following signature:

func(ctx iris.Context, username, password string) (any, bool)

This function is responsible for validating the username and password. It returns a user object (or any other type) and a boolean indicating whether the authentication was successful.

User Structure (Helper)

While the middleware does not require a specific user structure, you can use a helper structure to manage user data more conveniently. Here is an example of a user structure:

type User struct {
	Username string   `json:"username"`
	Password string   `json:"password"`
	Roles    []string `json:"roles"`
}

In-Memory User Storage

You can store users in memory using a slice of user structures. This is useful for small applications or testing purposes.

var users = []User{
	{"admin", "admin", []string{"admin"}},
	{"kataras", "kataras_pass", []string{"manager", "author"}},
	{"george", "george_pass", []string{"member"}},
	{"john", "john_pass", []string{}},
}

Basic Setup

To set up the middleware, create an instance of basicauth.Options and pass it to basicauth.New.

opts := basicauth.Options{
	Realm: basicauth.DefaultRealm,
	MaxAge: 10 * time.Minute,
	GC: basicauth.GC{
		Every: 2 * time.Hour,
	},
	Allow: basicauth.AllowUsers(users),
}

auth := basicauth.New(opts)

Using a File for User Storage

You can load users from a file (JSON or YAML). This is useful for applications where user data changes frequently.

auth := basicauth.Load("users.yml")

BCRYPT Option

The BCRYPT option allows you to use bcrypt for password hashing. Bcrypt is a password hashing function designed to be computationally intensive to resist brute-force attacks. It is widely used for securely storing passwords.

auth := basicauth.Load("users.yml", basicauth.BCRYPT)

You can also use the BCRYPT option with other user fetching methods, such as in-memory or database storage.

Using a Database for User Storage

For more dynamic user management, you can validate users against a database. Here is an example of how to set up the middleware using a MySQL database:

package main

import (
 "context"
 "database/sql"
 "fmt"
 "os"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/basicauth"

 _ "github.com/go-sql-driver/mysql"
)

type User struct {
 ID       int64  `db:"id" json:"id"`
 Username string `db:"username" json:"username"`
 Password string `db:"password" json:"password"`
 Email    string `db:"email" json:"email"`
}

func (u User) GetUsername() string {
 return u.Username
}

func (u User) GetPassword() string {
 return u.Password
}

func main() {
 dsn := fmt.Sprintf("%s:%s@tcp(%s:3306)/%s?parseTime=true&charset=utf8mb4&collation=utf8mb4_unicode_ci",
  getenv("MYSQL_USER", "user_myapp"),
  getenv("MYSQL_PASSWORD", "dbpassword"),

 get

env("MYSQL_HOST", "localhost"),
  getenv("MYSQL_DATABASE", "myapp"),
 )
 db, err := connect(dsn)
 if err != nil {
  panic(err)
 }

 // Validate a user from database.
 allowFunc := func(ctx iris.Context, username, password string) (any, bool) {
  user, err := db.getUserByUsernameAndPassword(context.Background(), username, password)
  return user, err == nil
 }

 opts := basicauth.Options{
  Realm:        basicauth.DefaultRealm,
  ErrorHandler: basicauth.DefaultErrorHandler,
  Allow:        allowFunc,
 }

 auth := basicauth.New(opts)

 app := iris.New()
 app.Use(auth)
 app.Get("/", index)
 app.Listen(":8080")
}

func index(ctx iris.Context) {
 user, _ := ctx.User().GetRaw()
 // user is a type of main.User
 ctx.JSON(user)
}

Custom Error Handling

You can customize the error handling behavior by setting the ErrorHandler field in the basicauth.Options.

opts := basicauth.Options{
	ErrorHandler: func(ctx iris.Context, err error) {
		ctx.StatusCode(iris.StatusUnauthorized)
		ctx.JSON(iris.Map{"error": "Unauthorized"})
	},
}

Session Expiration

The middleware supports session expiration. You can set the MaxAge field to specify the duration after which the user must re-authenticate.

opts := basicauth.Options{
	MaxAge: 10 * time.Minute,
}

Garbage Collection

To clear expired users from memory, you can set the GC field.

opts := basicauth.Options{
	GC: basicauth.GC{
		Every: 2 * time.Hour,
	},
}

Testing Handlers with BasicAuth Middleware

To test handlers that use the BasicAuth middleware, you can use the

httptest

package provided by Iris. Here is an example of how to test a handler:

package main_test

import (
 "testing"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/httptest"
 "github.com/kataras/iris/v12/middleware/basicauth"
)

func TestIndexHandler(t *testing.T) {
 opts := basicauth.Options{
  Realm: basicauth.DefaultRealm,
  Allow: basicauth.AllowUsers(users),
 }

 auth := basicauth.New(opts)

 app := iris.New()
 app.Use(auth)
 app.Get("/", index)

 e := httptest.New(t, app)

 // Test with valid credentials
 e.GET("/").WithBasicAuth("admin", "admin").Expect().Status(httptest.StatusOK).JSON().Object().Value("username").Equal("admin")

 // Test with invalid credentials
 e.GET("/").WithBasicAuth("admin", "wrongpassword").Expect().Status(httptest.StatusUnauthorized)
}

Example

Here is a complete example that demonstrates how to set up the middleware with in-memory user storage:

package main

import (
 "time"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/basicauth"
)

type User struct {
 Username string   `json:"username"`
 Password string   `json:"password"`
 Roles    []string `json:"roles"`
}

var users = []User{
 {"admin", "admin", []string{"admin"}},
 {"kataras", "kataras_pass", []string{"manager", "author"}},
 {"george", "george_pass", []string{"member"}},
 {"john", "john_pass", []string{}},
}

func main() {
 opts := basicauth.Options{
  Realm: basicauth.DefaultRealm,
  MaxAge: 10 * time.Minute,
  GC: basicauth.GC{
   Every: 2 * time.Hour,
  },
  Allow: basicauth.AllowUsers(users),
 }

 auth := basicauth.New(opts)

 app := iris.New()
 app.Use(auth)
 app.Get("/", index)
 app.Listen(":8080")
}

func index(ctx iris.Context) {
 user, _ := ctx.User().GetRaw()
 ctx.JSON(user)
}

Conclusion

The Basic Authentication middleware provides a comprehensive solution for securing your Iris web applications. With support for various user storage methods, advanced features like password encryption and custom error handling, and easy integration, it is a powerful tool for developers.

Overview

The rate middleware provides rate limiting capabilities for the Iris web framework. It allows developers to control the rate of requests to their applications, ensuring fair usage and preventing abuse. The middleware is based on the token bucket algorithm, which is a popular method for rate limiting.

Installation

To use the rate middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v12/middleware/rate"

Usage

Basic Setup

To use the rate limiter, you need to create an Iris application and register the middleware. Below is an example of how to set up the rate limiter:

package main

import (
 "time"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/rate"
)

func main() {
 app := iris.New()
 app.Logger().SetLevel("debug")

 limit := rate.Limit(1, 5, rate.PurgeEvery(time.Minute, 5*time.Minute))
 app.Use(limit)

 app.Get("/", index)
 app.Get("/other", other)

 app.Listen(":8080")
}

func index(ctx iris.Context) {
 ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
 ctx.HTML("<h1>Other Page</h1>")
}

This example allows 1 request per second with a maximum burst size of 5. It also purges old entries every minute if they haven’t been seen for 5 minutes.

Using rate.Every Helper

This example demonstrates how to use the rate.Every helper to set up a rate limiter:

package main

import (
 "time"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/rate"
)

func main() {
 app := iris.New()
 app.Logger().SetLevel("debug")

 // Use rate.Every helper to set up the rate limiter.
 limit := rate.Limit(rate.Every(time.Minute), 5)
 app.Use(limit)

 app.Get("/", index)
 app.Get("/other", other)

 app.Listen(":8080")
}

func index(ctx iris.Context) {
 ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
 ctx.HTML("<h1>Other Page</h1>")
}

Using API Key for Rate Limiting

This example demonstrates how to set up a rate limiter that uses an API key instead of the client’s remote IP address:

package main

import (
 "time"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/rate"
)

func main() {
 app := iris.New()
 app.Logger().SetLevel("debug")

 // Use API key for rate limiting.
 app.Use(useAPIKey)

 limit := rate.Limit(rate.Every(time.Minute), 300, rate.PurgeEvery(5*time.Minute, 15*time.Minute))
 app.Use(limit)

 app.Get("/list", list)

 app.Listen(":8080")
}

func useAPIKey(ctx iris.Context) {
 apiKey := ctx.Header("X-API-Key")
 if apiKey == "" {
  ctx.StopWithStatus(iris.StatusForbidden)
  return
 }

 rate.SetIdentifier(ctx, apiKey)
 ctx.Next()
}

func list(ctx iris.Context) {
 ctx.JSON(iris.Map{"key": "value"})
}

Custom Exceed Handler

This example demonstrates how to set a custom handler to be executed when the rate limit is exceeded:

package main

import (
 "time"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/rate"
)

func main() {
 app := iris.New()
 app.Logger().SetLevel("debug")

 // Set a custom exceed handler.
 limit := rate.Limit(1, 5, rate.ExceedHandler(func(ctx iris.Context) {
  ctx.StopWithStatus(429)
 }))
 app.Use(limit)

 app.Get("/", index)
 app.Get("/other", other)

 app.Listen(":8080")
}

func index(ctx iris.Context) {
 ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
 ctx.HTML("<h1>Other Page</h1>")
}

Custom Client Data

This example demonstrates how to store custom data for each client:

package main

import (
 "time"

 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/rate"
)

func main() {
 app := iris.New()
 app.Logger().SetLevel("debug")

 // Store custom data for each client.
 limit := rate.Limit(1, 5, rate.ClientData(func(ctx iris.Context) any {
  return ctx.RemoteAddr()
 }))
 app.Use(limit)

 app.Get("/", index)
 app.Get("/other", other)

 app.Listen(":8080")
}

func index(ctx iris.Context) {
 ctx.HTML("<h1>Index Page</h1>")
}

func other(ctx iris.Context) {
 ctx.HTML("<h1>Other Page</h1>")
}

Explanation

• Rate Limiting: The rate.Limit function is used to create a new rate limiter. It takes three parameters:

limit: The maximum number of requests allowed per second.

burst: The maximum burst size.

options: Additional options such as PurgeEvery for cleaning up old entries.

• Token Bucket Algorithm: This algorithm controls the rate of requests by maintaining a bucket of tokens. Each request consumes a token, and tokens are added to the bucket at a fixed rate. If the bucket is empty, the request is denied.

Token Bucket Algorithm

The token bucket algorithm is a simple and efficient way to control the rate of requests. It works as follows:

1. Initialization: A bucket is initialized with a certain number of tokens.
2. Token Addition: Tokens are added to the bucket at a fixed rate.
3. Request Handling: Each request consumes a token. If the bucket is empty, the request is denied.
4. Burst Handling: The bucket can hold a maximum number of tokens, allowing for bursts of traffic.

For more details, refer to the Wikipedia article on Token Bucket.

Conclusion

This middleware provides a robust and flexible way to implement rate limiting in your Iris applications. By using the token bucket algorithm, it ensures fair usage and prevents abuse, making your application more reliable and secure.

For more examples and detailed usage, refer to the official Iris documentation.

The accesslog middleware for the Iris web framework provides detailed logging for incoming HTTP requests. This middleware is highly configurable and can log various aspects of the request and response, including custom fields.

Features

• Logs request and response details.
• Supports multiple output formats (JSON, CSV, custom templates).
• Can log to multiple destinations (files, stdout, etc.).
• Asynchronous logging support.
• Customizable log fields.
• Middleware can be conditionally applied.

Installation

To use the accesslog middleware, you need to import it in your Iris application:

import (
    "github.com/kataras/iris/v12"
    "github.com/kataras/iris/v12/middleware/accesslog"
)

Basic Usage

Here is a basic example of how to use the accesslog middleware in an Iris application:

package main

import (
    "github.com/kataras/iris/v12"
    "github.com/kataras/iris/v12/middleware/accesslog"
)

func makeAccessLog() *accesslog.AccessLog {
    ac := accesslog.File("./access.log")
    ac.Delim = '|'
    ac.TimeFormat = "2006-01-02 15:04:05"
    ac.Async = false
    ac.IP = true
    ac.BytesReceivedBody = true
    ac.BytesSentBody = true
    ac.BytesReceived = false
    ac.BytesSent = false
    ac.RequestBody = true
    ac.ResponseBody = false
    ac.KeepMultiLineError = true
    ac.PanicLog = accesslog.LogHandler
    ac.SetFormatter(&accesslog.JSON{
        Indent:    "  ",
        HumanTime: true,
    })
    return ac
}

func main() {
    ac := makeAccessLog()
    defer ac.Close()
    app := iris.New()
    app.UseRouter(ac.Handler)
    app.Get("/", func(ctx iris.Context) {
        ctx.WriteString("OK")
    })
    app.Listen(":8080")
}

Configuration Options

Output Destination

You can set the output destination for the logs using the File or New functions:

ac := accesslog.File("./access.log")
// or
ac := accesslog.New(os.Stdout)

Log Format

The default log format is:

Time|Latency|Code|Method|Path|IP|Path Params Query Fields|Bytes Received|Bytes Sent|Request|Response|

You can customize the log format using different formatters:

JSON Formatter

ac.SetFormatter(&accesslog.JSON{
    Indent:    "  ",
    HumanTime: true,
})

CSV Formatter

ac.SetFormatter(&accesslog.CSV{})

Custom Template Formatter

ac.SetFormatter(&accesslog.Template{Text: "{{.Code}}"})

Custom Fields

You can add custom fields to the log entries:

ac.AddFields(func(ctx iris.Context, f *accesslog.Fields) {
    for k, v := range ctx.Request().Header {
        value := strings.Join(v, ", ")
        f.Set("request.header."+k, value)
    }
})

Asynchronous Logging

Enable asynchronous logging to improve performance:

ac.Async = true

Conditional Logging

You can skip logging for specific routes or conditions:

app.UseRouter(accesslog.SkipHandler)

Advanced Usage

Logging to Multiple Destinations

You can log to multiple destinations using io.MultiWriter:

ac.SetOutput(io.MultiWriter(os.Stdout, accesslog.File("./access.log")))

Custom Clock

You can set a custom clock for the log timestamps, useful for testing:

ac.Clock = accesslog.TClock(time.Now())

Middleware Integration

Integrate the accesslog middleware with other middlewares:

app.UseRouter(ac.Handler)
app.UseRouter(otherMiddleware)

Examples

Log Requests to a JSON File

ac := accesslog.File("access_log.json")
ac.SetFormatter(&accesslog.JSON{
    Indent:    "  ",
    HumanTime: true,
})
app.UseRouter(ac.Handler)

Using Log Rotation

Refer to the log rotation example for more details.

Custom Fields and Template

Refer to the custom fields and template example for more details.

Listen and Render Logs to a Client

Refer to the log broker example for more details.

Conclusion

The accesslog middleware for Iris is a powerful tool for logging HTTP requests and responses. With its flexible configuration options and support for custom fields and formats, it can be tailored to meet the needs of any application.

For more examples and detailed usage, refer to the official Iris documentation.

Rewrite can help you achieve better SEO results by redirecting old or unwanted URLs to new ones, enforcing a primary subdomain, or simplifying complex URL structures.

How to Install Rewrite

To install Rewrite, you need to have Go installed on your system. Then, you can use the go get command to download and install the package:

$ go get github.com/kataras/rewrite

How to Use Rewrite

You can load rewrite options in two ways:

1. Through code using the New function and Handler method. This way, you can handle parse errors and create rules programmatically.

2. Or through a YAML file using the Load function which returns a func(http.Handler) http.Handler. This is the most common and simplest way. It panics on parse errors.

The syntax of the rewrite rules is:

REDIRECT_CODE_DIGITS PATTERN_REGEX TARGET_REPL

Where:

- REDIRECT_CODE_DIGITS is the HTTP status code to use for the redirection, such as 301 (Moved Permanently) or 302 (Found).

- PATTERN_REGEX is the regular expression that matches the request URL path, subdomain or host.

- TARGET_REPL is the replacement string that contains the new URL path, subdomain or host.

For example:

301 /seo/(.*) /$1

This rule redirects all requests from relative path /seo/*` to `/* using the 301 HTTP status code.

You can also use a special option called PrimarySubdomain to redirect all requests from the root domain to a specific subdomain, such as www.

For example:

PrimarySubdomain: www

This option redirects all requests from example.com to www.example.com.

Examples

Let’s write a simple application that follows these redirect rules:

- Redirects `/seo/*` to `/*`

- Redirects `/docs/v12*` to `/docs`

- Redirects `/old (.*)` to `/`

- Redirects root domain requests to `www.`

The code would look like this:

package main

import (
  "net/http"

  "github.com/kataras/rewrite"
)

func main() {
  mux := http.NewServeMux()
  // […routes]
  // Load the redirect rules from a YAML file.
  redirects := rewrite.Load("redirects.yml")
  // Wrap the router with the rewrite middleware.
  http.ListenAndServe(":8080", redirects(mux))
}

The YAML file would look like this:

RedirectMatch:
  # Redirects /seo/* to /*
  - 301 /seo/(.*) /$1
  # Redirects /docs/v12* to /docs
  - 301 /docs/v12(.*) /docs
  # Redirects /old (.*) to /
  - 301 /old(.*) /
# Redirects root domain requests to www.
PrimarySubdomain: www

That’s it! Now you can test your application and see how it redirects the requests according to your rules.

You can find more examples in the `_examples` folder of the GitHub repository: https://github.com/kataras/rewrite/tree/main/_examples

Conclusion

Rewrite is a handy package that lets you rewrite URLs in Go with ease. It is compatible with any net/http router or framework and supports regular expressions for flexible matching and replacing. It can help you improve your SEO performance by redirecting old or unwanted URLs to new ones, enforcing a primary subdomain, or simplifying complex URL structures.

If you want to learn more about Rewrite, you can check out its GitHub repository: https://github.com/kataras/rewrite

I hope you enjoyed this article and found it useful. If you have any feedback or questions, feel free to leave a comment below. Thank you for reading! 😊

Iris is a fast, simple yet fully featured and very efficient web framework for Go. It provides a beautifully expressive and easy to use foundation for your next website or API. One of the features that Iris offers the middleware/basicauth sub-package, which allows you to implement basic authentication for your web applications.

Basic authentication is a simple and widely used scheme that requires the client to provide a username and password to access a protected resource. The credentials are encoded with Base64 and sent in the HTTP header. However, they are not encrypted or hashed, so basic authentication should be used in conjunction with HTTPS to provide confidentiality.

In this article, we will show you how to use the basicauth middleware to add basic authentication to your Iris handlers.

Installing Iris and BasicAuth Middleware

To use the BasicAuth middleware, you need to install Iris first. You can do that by running the following command in your terminal:

go get github.com/kataras/iris/v12@latest

This will download and install the latest version of Iris and its dependencies. You can also specify a specific version if you want.

Next, you need to import the middleware/basicauth sub-package in your Go code. You can do that by adding the following line at the top of your file:

import "github.com/kataras/iris/v12/middleware/basicauth"

This will make the basicauth package available for your use.

Creating a basic authentication middleware

To create a basic authentication middleware, you need to use the basicauth.New function from the basicauth package. This function accepts a basicauth.Options struct that contains various options for configuring the middleware. The most important option is the Allow field, which is a function that takes a username and password as arguments and returns true if they are valid or false otherwise. You can use one of the helper methods from the basicauth package to create this function from different sources of valid credentials. They are:

- basicauth.AllowUsers: This method takes a map of usernames and passwords and returns an Allow function that uses the given map as the source of valid credentials. This is useful if you want to create the Allow function from a predefined map of users.

- basicauth.AllowUsersFile: This method takes a JSON or YAML filename and returns an Allow function that uses the file as the source of valid credentials. The file should contain an array of objects with username and password fields. This is useful if you want to store your users in an external file instead of in your code.

- basicauth.BCRYPT: This method takes a UserAuthOptions struct and modifies it to use bcrypt hashing for comparing passwords. This is useful if you want to store hashed passwords instead of plain ones in your users map or file. You can pass this method as an argument to the basicauth.AllowUsers or basicauth.AllowUsersFile helper methods to create an Allow function that uses bcrypt hashing.

You can also set other options such as Realm, Expires, ErrorHandler and more.

The basicauth.New function returns an iris.Handler, which is a function that takes an iris.Context as an argument and performs some actions on it. You can register this handler as a middleware for your routes or parties using methods such as Use, UseGlobal, or UseRouter.

Here is an example of how to create and use a basic authentication middleware using a map of users:

package main

import (
 "github.com/kataras/iris/v12"
 "github.com/kataras/iris/v12/middleware/basicauth"
)

func main() {
 app := iris.New()

 // Create a map of usernames and passwords.
 users := map[string]string{
  "myusername": "mypassword",
  "admin":      "admin",
 }

 // Create an Allow function using basicauth.AllowUsers helper method.
 allow := basicauth.AllowUsers(users)

 // Create a basic authentication middleware using basicauth.New.
 auth := basicauth.New(basicauth.Options{
  Realm: basicauth.DefaultRealm,
  Allow: allow,
 })

 // Register the auth handler as a global middleware using UseGlobal.
 app.UseGlobal(auth)

 // Register some routes that require basic authentication.
 app.Get("/", func(ctx iris.Context) {
  username, password, _ := ctx.User()
  ctx.Writef("%s %s: You are authenticated", username, password)
 })

 app.Get("/admin", func(ctx iris.Context) {
  username, _, _ := ctx.User()
  if username == "admin" {
   ctx.WriteString("Hello admin")
  } else {
   ctx.StopWithText(iris.StatusForbidden, "Only admin can access this page")
  }
 })

 app.Get("/logout", func(ctx iris.Context) {
  ctx.Logout()
  ctx.Redirect("/")
 })

 app.Listen(":8080")
}

Testing the basic authentication middleware

To test the basic authentication middleware, you can run the above code and visit http://localhost:8080 in your browser. You should see a prompt asking you for your username and password. If you enter one of the valid credentials from the users map, you should see a message saying that you are authenticated. If you enter an invalid credential, you should see an error message saying that authorization is required.

You can also visit http://localhost:8080/admin to see a page that is only accessible by the admin user. If you enter the admin credential, you should see a message saying hello admin. If you enter any other credential, you should see a message saying that only admin can access this page.

You can also visit http://localhost:8080/logout to log out from the basic authentication and clear the cookie. You should be redirected to the home page and see the prompt again if you refresh the page.

Conclusion

In this article, we have learned how to use the middleware/basicauth sub-package to create a basic authentication middleware for your Iris handlers. We have seen how to configure the middleware with various options, how to register it as a global or route-specific middleware, and how to test it in the browser. We have also seen how to use different helper methods to create the Allow function from different sources of valid credentials, and how to use bcrypt hashing to store hashed passwords. We have also seen how to use the Context.User() method to get the username and password of the authenticated user, and how to use the Context.Logout() method to log out from the basic authentication.

We hope that this article has helped you understand how to use Iris and basic authentication for your web applications. For more information and examples, you can visit the official documentation of Iris at https://www.iris-go.com/docs/#/?id=using-basic-authentication and the GitHub repository of Iris at https://github.com/kataras/iris/tree/master/_examples/auth/basicauth. Thank you for reading!

The article was also published at:

https://dev.to/kataras/how-to-use-iris-and-basic-authentication-5hjm

A guide to using PG middleware, a package for Iris that provides easy and type-safe access to PostgreSQL database.

Iris is a fast and lightweight web framework for Go that offers a rich set of features and a high-performance engine. PostgreSQL is a powerful and reliable relational database system that supports advanced data types and functions. Together, they can form a solid foundation for building modern web applications.

But how can you connect Iris and PostgreSQL in a simple and type-safe way? How can you perform common database operations without writing too much boilerplate code? How can you handle transactions, schema creation, query tracing and error handling in a consistent manner?

The answer is PG middleware, a package for Iris that provides easy and type-safe access to PostgreSQL database. In this article, we will show you how to use PG middleware to create a simple REST API for managing customers.

What is PG middleware?

PG middleware is a package for Iris web framework that provides easy and type-safe access to PostgreSQL database. It has the following features:

• It supports PostgreSQL 9.5 and above.
• It uses pg package and pgx driver under the hood.
• It supports transactions, schema creation and validation, query tracing and error handling.
• It allows registering custom types and table models using a schema object.
• It provides a generic repository interface for common CRUD operations.

How to install PG middleware?

To install PG middleware, you need to use the following command:

go get github.com/iris-contrib/middleware/pg@master

How to use PG middleware?

To use PG middleware, you need to follow these steps:

1. Import the package in your code:

import (
    "github.com/kataras/iris/v12"

    "github.com/iris-contrib/middleware/pg"
)

1. Define your database table models as structs with pg tags:

// The Customer database table model.
type Customer struct {
    ID   string `json:"id" pg:"type=uuid,primary"`
    Name string `json:"name" pg:"type=varchar(255)"`
}

The json tag defines how the struct fields are encoded or decoded as JSON. The pg tag defines how the struct fields are mapped to the database table columns. You can specify the column type, constraints, indexes and other options using the pg tag. Read more at pg repository.

1. Create a schema object and register your models:

schema := pg.NewSchema()
schema.MustRegister("customers", Customer{})

The schema object is used to store the metadata of your database tables and models. You need to register your models with the schema object using the MustRegister method. The first argument is the table name, and the second argument is the model type.

1. Create a PG middleware instance with the schema and database options:

opts := pg.Options{
    Host:          "localhost",
    Port:          5432,
    User:          "postgres",
    Password:      "admin!123",
    DBName:        "test_db",
    Schema:        "public",
    SSLMode:       "disable",
    Transactional: true,
    Trace:         true,
    CreateSchema:  true,
    CheckSchema:   true,
    ErrorHandler: func(ctx iris.Context, err error) {
        ctx.StopWithError(iris.StatusInternalServerError, err)
    },
}

p := pg.New(schema, opts)

The options struct defines the configuration parameters for connecting to the database and using the middleware features. You need to specify the host, port, user, password, dbname, schema and sslmode fields for establishing the connection. You can also enable or disable the transactional feature, which wraps each request handler in a database transaction. You can also enable or disable the trace feature, which logs each query executed by the middleware. You can also enable or disable the createSchema feature, which creates the schema if it doesn’t exist in the database. You can also enable or disable the checkSchema feature, which checks the schema for missing tables and columns and reports any discrepancies. You can also provide an errorHandler function, which handles any errors occurred during the middleware execution.

The New function creates a new PG middleware instance with the given schema and options.

1. Attach the middleware handler to your Iris app or routes:

app := iris.New()

postgresMiddleware := newPostgresMiddleware()

{
    customerAPI := app.Party("/api/customer", postgresMiddleware)
    customerAPI.Post("/", createCustomer)
    customerAPI.Get("/{id:uuid}", getCustomer)
    customerAPI.Put("/{id:uuid}", updateCustomer)
    customerAPI.Delete("/{id:uuid}", deleteCustomer)
}

The middleware handler is a function that takes an Iris context and calls the next handler in the chain. You can attach the middleware handler to your Iris app or routes using the Use or Party methods. In this example, we create a subrouter for the customer API and apply the middleware handler to it.

1. Use the pg.DB or pg.Repository package-level functions to access the database instance or the repository interface in your handlers:

func createCustomer(ctx iris.Context) {
    var payload = struct {
        Name string `json:"name"`
    }{}
    err := ctx.ReadJSON(&payload)
    if err != nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }

    // Get the current database instance through pg.DB middleware
    // package-level function.
    // db := pg.DB(ctx)
    // [Work with db instance...]
    // OR, initialize a new repository of Customer type and
    // work with it (type-safety).
    customers := pg.Repository[Customer](ctx)
    // Insert a new Customer.
    customer := Customer{
        Name: payload.Name,
    }
    err = customers.InsertSingle(ctx, customer, &customer.ID)
    if err != nil {
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }
    // Display the result ID.
    ctx.StatusCode(iris.StatusCreated)
    ctx.JSON(iris.Map{"id": customer.ID})
}

func getCustomer(ctx iris.Context) {
    // Get the id from the path parameter.
    id := ctx.Params().Get("id")
    // Get the repository of Customer type through pg.Repository
    // middleware package-level function.
    customers := pg.Repository[Customer](ctx)
    // Get the customer by the id.
    customer, err := customers.SelectByID(ctx, id)
    if err != nil {
        if pg.IsErrNoRows(err) {
            ctx.StopWithStatus(iris.StatusNotFound)
        } else {
            ctx.StopWithError(iris.StatusInternalServerError, err)
        }
        return
    }
    // Display the retrieved Customer.
    ctx.JSON(customer)
}

func updateCustomer(ctx iris.Context) {
    // Get the id from the path parameter.
    id := ctx.Params().Get("id")
    var payload = struct {
        Name string `json:"name"`
    }{}
    err := ctx.ReadJSON(&payload)
    if err != nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }
    // Get the repository of Customer type through pg.Repository
    // middleware package-level function.
    customers := pg.Repository[Customer](ctx)
    // Update the customer by the id and name.
    customer := Customer{
        ID: id,
        Name: payload.Name,
    }
    _, err = customers.UpdateOnlyColumns(ctx, []string{"name"}, customer)
    // OR customers.Update(ctx, customer)
    if err != nil {
        if pg.IsErrNoRows(err) {
            ctx.StopWithStatus(iris.StatusNotFound)
        } else {
            ctx.StopWithError(iris.StatusInternalServerError, err)
        }
        return
    }
    // Display a success message.
    ctx.StatusCode(iris.StatusOK)
    ctx.JSON(iris.Map{"message": "Customer updated successfully"})
}

func deleteCustomer(ctx iris.Context) {
    // Get the id from the path parameter.
    id := ctx.Params().Get("id")
    // Get the repository of Customer type through pg.Repository
    // middleware package-level function.
    customers := pg.Repository[Customer](ctx)
    // Delete the customer by the id.
    _, err := customers.Delete(ctx, Customer{ID: id})
    if err != nil {
        if pg.IsErrNoRows(err) {
            ctx.StopWithStatus(iris.StatusNotFound)
        } else {
            ctx.StopWithError(iris.StatusInternalServerError, err)
        }
        return
    }
    // Display a success message.
    ctx.StatusCode(iris.StatusOK)
    ctx.JSON(iris.Map{"message": "Customer deleted successfully"})
}

The pg.DB function returns the current database instance associated with the Iris context. You can use this instance to perform any database operations using the pg package API. The pg.Repository function returns a generic repository interface for the given model type associated with the Iris context. You can use this interface to perform common CRUD operations using type-safe methods. In this example, we use the repository interface to insert and select customers.

How to run the example?

To run the example, you need to:

1. Clone the PG middleware repository and navigate to the _examples/basic folder.
2. Install the dependencies using go mod tidy.
3. Start a PostgreSQL server and create a database named test_db.
4. Run the main.go file using go run main.go.
5. Use a tool like Postman or curl to test the API endpoints:

# Create a new customer
curl -X POST -H "Content-Type: application/json" -d '{"name":"Alice"}' http://localhost:8080/api/customer

# Get a customer by id
curl -X GET http://localhost:8080/api/customer/1f8c9a7c-6b7c-4f0e-8a1d-9f2a9c3b7b8e

# Update a customer by id
curl -X PUT -H "Content-Type: application/json" -d '{"name":"Bob"}' http://localhost:8080/api/customer/1f8c9a7c-6b7c-4f0e-8a1d-9f2a9c3b7b8e

# Delete a customer by id
curl -X DELETE http://localhost:8080/api/customer/1f8c9a7c-6b7c-4f0e-8a1d-9f2a9c3b7b8e

Conclusion

In this article, we have shown you how to use PG middleware to connect Iris and PostgreSQL in a simple and type-safe way. We have also demonstrated how to use PG middleware features such as transactions, schema creation and validation, query tracing and error handling. We have also shown how to use PG middleware to create a simple REST API for managing customers.

The article was also published at:

1. https://dev.to/kataras/how-to-use-iris-and-postgresql-for-web-development-3kka
2. https://medium.com/@kataras/how-to-use-iris-and-postgresql-for-web-development-e8c46d72f1e6
3. https://twitter.com/TheGoDev/status/1676701488544874498
4. https://twitter.com/TheDatabaseDev/status/1676748294595174401

We hope you find PG middleware useful and easy to use. If you have any feedback or questions, please feel free to open an issue or a pull request on GitHub. Thank you for reading!🙏

Hello folks,

It has been a long time since we talked about performance in Go.

There is no secret that Go has support for a large amount of template syntax nowadays. However, we’ve seen zero articles on how each of them performs. Here we are.

Intro

In this article we will run simple, easy to understand, mini benchmarks to find out which template parser renders faster. Keep in mind that speed is not always the case, you have to choose wisely the template parser to use because their features varies and depending your application’s needs you may be forced to use an under-performant parser instead.

We will compare the following 8 template engines/parsers:

1. Ace
2. Amber
3. Blocks
4. Django
5. Handlebars
6. HTML (standard html/template)
7. Jet
8. Pug

Each benchmark test consists of a template + layout + partial + template data (map). They all have the same response amount of total bytes. Amber, Ace and Pug parsers minifies the template before render, therefore, all other template file’s contents are minified too (no new lines and spaces between html blocks).

As always, my benchmark code is available for everyone but I will not tire you anymore by showing the code for each of them in the article, instead you can navigate here.

Benchmarks

Terminology

Name is the name of the template engine.

Reqs/sec is the avg number of total requests could be processed per second (the higher the better).

Latency is the amount of time it takes from when a request is made by the client to the time it takes for the response to get back to that client (the smaller the better).

Throughput is the rate of production or the rate at which data are transferred (the higher the better, it depends from response length (body + headers).

Time To Complete is the total time (in seconds) the test completed (the smaller the better).

Results

📖 Fires 1000000 requests with 125 concurrent clients. It receives HTML response. The server handler sets some template data and renders a template file which consists of a layout and a partial footer.

And for those who like graphs, here you are:

As we’ve seen above, Amber is the fastest and Jet is the slowest one. Keep in mind that in Jet parser, we cache the templates by ourselves before server ran — its default behavior is to cache them at runtime instead, so it could be even slower natively.

If you want to run the benchmarks by yourself, please follow the guide below:

1. Install the Go Programming Language
2. Download and unzip the test files using git clone
3. Open a terminal inside the test files directory and execute the commands below:

$ go get -u github.com/kataras/server-benchmarks
$ go get -u github.com/codesenberg/bombardier
$ server-benchmarks --wait-run=3s -o ./results

Follow my Twitter and GitHub accounts.

Have fun 🥳 and keep yourself strong in these difficult and restless times we live in💪

Yours,
Gerasimos Maropoulos. Author of the Iris Web Framework

What’s the fastest template engine in Go? was originally published in HackerNoon.com on Medium, where people are continuing the conversation by highlighting and responding to this story.

Vue.js is a front-end framework for building web applications using javascript. It has a blazing fast Virtual DOM renderer.

Iris is a back-end framework for building web applications using The Go Programming Language (disclaimer: author here). It’s one of the fastest and featured web frameworks out there. We wanna use this to serve our “todo service”.

The Tools

Programming Languages are just tools for us, but we need a safe, fast and “cross-platform” programming language to power our service.

Go is a rapidly growing open source programming language designed for building simple, fast, and reliable software. Take a look here which great companies use Go to power their services.

Install the Go Programming Language

The article does not contain an introduction to the language itself, if you’re a newcomer I recommend you to bookmark this article, learn the language’s fundamentals and come back later on.

The Dependencies

Many articles have been written, in the past, that lead developers not to use a web framework because they are useless and “bad”. I have to tell you that there is no such thing, it always depends on the (web) framework that you’re going to use. At production environment, we don’t have the time or the experience to code everything that we wanna use in the applications, and if we could are we sure that we can do better and safely than others? In short term: Good frameworks are helpful tools for any developer, company or startup and “bad” frameworks are waste of time, crystal clear.

You’ll need two dependencies:

1. Vue.js, for our client-side requirements. Download it from here, latest v2.
2. The Iris Web Framework, for our server-side requirements. Can be found here, latest v12.

If you have Go already installed then just execute go get github.com/kataras/iris/v12@latestto install the Iris Web Framework.

Start

If we are all in the same page, it’s time to learn how we can create a live todo application that will be easy to deploy and extend even more!

We’re going to use a vue.js todo application which uses browser’s local storage and doesn’t have any user-specified features like live sync between browser’s tabs, you can find the original version inside the vue’s docs.

• web/public/js/app.js
• web/public/index.html
• todo/item.go
• todo/service.go
• web/controllers/todo_controller.go
• web/main.go

Read the comments in the source code, they may be very helpful

The client-side (vue.js)

Let’s add our view, the html.

The server-side (iris)

Our view model.

Our service.

We are going to use some of the MVC functionalities of the iris web framework here but you can do the same with the standard API as well.

And finally our main application’s endpoind.

Run the Iris web server you’ve just created by executing go run main.go from your current path (%GOPATH%/src/%your_folder%/web/).

$ go run main.go
Now listening on: http://localhost:8080
Application Started. Press CTRL+C to shut down.
_

Open one or more browser tabs at: http://localhost:8080 and have fun!

Download the Source Code

The whole project, all the files you saw in this article are located at: https://github.com/kataras/iris/tree/master/_examples/tutorial/vuejs-todo-mvc

References

https://vuejs.org/v2/examples/todomvc.html (using browser’s local storage)

https://github.com/kataras/iris/tree/master/_examples/mvc (mvc examples and features overview repository)

Thank you, once again

Happy new year and thank you for your pattience, once again:) Don’t hesitate to post any questions and provide feedback(I’m very active dev therefore you will be heard here!)

Don’t forget to check out my medium profile and twitter as well, I’m posting some (useful) stuff there too:)

• https://medium.com/@kataras
• https://twitter.com/MakisMaropoulos

A Todo MVC Application using Iris and Vue.js was originally published in HackerNoon.com on Medium, where people are continuing the conversation by highlighting and responding to this story.