DEV Community: Gerasimos (Makis) Maropoulos

Introducing llms.txt — AI Transparency for the Iris Web Framework

Gerasimos (Makis) Maropoulos — Sat, 13 Sep 2025 09:38:21 +0000

Why Transparency Matters in AI

As artificial intelligence becomes more embedded in developer tooling, open-source frameworks must lead with transparency, ethics, and trust. That’s why the Iris Web Framework now includes a new file: llms.txt.

This document outlines how Iris uses—or plans to use—large language models (LLMs) to enhance developer experience, documentation, and support.

What’s Inside `llms.txt`

The file includes:

✅ Planned LLM integrations for documentation, code generation, and developer support
✅ Compliance with the EU AI Act and global standards like ISO/IEC 42001
✅ Ethical safeguards including bias mitigation and human oversight
✅ Open-source governance with community involvement and transparency

Use Cases We’re Exploring

While Iris doesn’t currently host or train LLMs directly, we’re experimenting with:

AI-powered documentation summaries
Conversational developer support agents
Code scaffolding for common web patterns
Automated test generation and refactoring suggestions
Natural language search across examples and docs

Built for Developers, With Developers

All AI features are optional, clearly labeled, and designed to assist—not replace—human developers. We’re committed to keeping the Iris experience fast, lightweight, and developer-first.

A Living Document

llms.txt is versioned and will evolve with the framework. You can view it here and contribute via GitHub.

Join the Conversation

We welcome feedback, ideas, and concerns. Let’s build the future of web development—responsibly and collaboratively.

— Gerasimos Maropoulos

Creator of Iris Web Framework

RFC: HTTP Wire Errors

Gerasimos (Makis) Maropoulos — Sun, 01 Dec 2024 12:52:42 +0000

Overview

This RFC proposes a standardized approach for handling and representing HTTP wire errors in a consistent and structured manner. The goal is to provide clear and detailed error responses that can be easily understood and processed by clients.

Error Response Structure

Each error response will follow a standardized JSON structure with the following fields:

id: A unique identifier for the error instance.
http_error_code: An object containing:
- canonical_name: A string representing the canonical name of the error.
- status: An integer representing the HTTP status code.
message: A short, human-readable summary of the error.
detail: A human-readable explanation specific to this occurrence of the error.
data (optional): Additional data related to the error.
validation (optional): An array of validation errors, each containing:
- field: The name of the field that caused the validation error.
- value: The invalid value provided.
- reason: A human-readable explanation of why the value is invalid.

Example

{
    "id": "unique-error-id",
    "http_error_code": {
        "canonical_name": "ERROR_NAME",
        "status": 400
    },
    "message": "short summary of the error",
    "detail": "detailed explanation of the error",
    "data": {
        "additional": "context-specific data"
    },
    "validation": [
        {
            "field": "field_name",
            "value": "invalid_value",
            "reason": "explanation of why the value is invalid"
        }
    ]
}

Canonical Error Names

The following canonical error names are defined:

INVALID_ARGUMENT: Indicates that the client provided an invalid argument.
FAILED_PRECONDITION: Indicates that the operation was rejected because the system is not in a state required for the operation's execution.
OUT_OF_RANGE: Indicates that an operation was attempted past the valid range.
UNSUPPORTED_MEDIA_TYPE: Indicates that the request entity has a media type which the server or resource does not support.
DEADLINE_EXCEEDED: Indicates that the deadline expired before the operation could complete.
NOT_FOUND: Indicates that the requested resource could not be found.
METHOD_NOT_ALLOWED: Indicates that the HTTP method used is not supported by the resource.
ALREADY_EXISTS: Indicates that the resource that a client tried to create already exists.
ABORTED: Indicates that the operation was aborted, typically due to a concurrency issue.
PERMISSION_DENIED: Indicates that the caller does not have permission to execute the specified operation.
UNAUTHENTICATED: Indicates that the request does not have valid authentication credentials for the operation.
RESOURCE_EXHAUSTED: Indicates that some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
TOO_LARGE: Indicates that the request entity is larger than limits defined by server.
UNIMPLEMENTED: Indicates that the operation is not implemented or not supported/enabled in this service.
UNAVAILABLE: Indicates that the service is currently unavailable.
INTERNAL: Indicates an internal server error.
DATA_LOSS: Indicates unrecoverable data loss or corruption.
UNKNOWN: Indicates an unknown error.
PAYMENT_REQUIRED: Indicates that payment is required to access the resource.
NOT_ACCEPTABLE: Indicates that the resource is not capable of generating content acceptable according to the Accept headers sent in the request.
PROXY_AUTH_REQUIRED: Indicates that the client must first authenticate itself with the proxy.
REQUEST_TIMEOUT: Indicates that the server timed out waiting for the request.
GONE: Indicates that the resource requested is no longer available and will not be available again.
LENGTH_REQUIRED: Indicates that the request did not specify the length of its content, which is required by the requested resource.
PRECONDITION_FAILED: Indicates that the server does not meet one of the preconditions that the requester put on the request.
REQUEST_URI_TOO_LONG: Indicates that the URI provided was too long for the server to process.
REQUESTED_RANGE_NOT_SATISFIABLE: Indicates that the server cannot supply the portion of the file requested.
EXPECTATION_FAILED: Indicates that the server cannot meet the requirements of the Expect request-header field.
IM_A_TEAPOT: Indicates that the server refuses to brew coffee because it is, permanently, a teapot.
MISDIRECTED_REQUEST: Indicates that the request was directed at a server that is not able to produce a response.
UNPROCESSABLE_ENTITY: Indicates that the server understands the content type of the request entity, but was unable to process the contained instructions.
LOCKED: Indicates that the resource that is being accessed is locked.
FAILED_DEPENDENCY: Indicates that the request failed due to failure of a previous request.
TOO_EARLY: Indicates that the server is unwilling to risk processing a request that might be replayed.
UPGRADE_REQUIRED: Indicates that the client should switch to a different protocol.
PRECONDITION_REQUIRED: Indicates that the origin server requires the request to be conditional.
REQUEST_HEADER_FIELDS_TOO_LARGE: Indicates that the server is unwilling to process the request because its header fields are too large.
UNAVAILABLE_FOR_LEGAL_REASONS: Indicates that the resource is unavailable for legal reasons.
HTTP_VERSION_NOT_SUPPORTED: Indicates that the server does not support the HTTP protocol version used in the request.
VARIANT_ALSO_NEGOTIATES: Indicates that the server has an internal configuration error.
INSUFFICIENT_STORAGE: Indicates that the server is unable to store the representation needed to complete the request.
LOOP_DETECTED: Indicates that the server detected an infinite loop while processing a request.
NOT_EXTENDED: Indicates that further extensions to the request are required for the server to fulfill it.
NETWORK_AUTHENTICATION_REQUIRED: Indicates that the client needs to authenticate to gain network access.
PAGE_EXPIRED: Indicates that the page has expired.
BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS: Indicates that the request was blocked by Windows Parental Controls.
INVALID_TOKEN: Indicates that the token provided is invalid.
TOKEN_REQUIRED: Indicates that a token is required to access the resource.
BANDWIDTH_LIMIT_EXCEEDED: Indicates that the bandwidth limit has been exceeded.
INVALID_SSL_CERTIFICATE: Indicates that the SSL certificate is invalid.
SITE_OVERLOADED: Indicates that the site is overloaded.
SITE_FROZEN: Indicates that the site is frozen.
NETWORK_READ_TIMEOUT: Indicates that there was a network read timeout error.

Error Handling

Invalid Argument

When the client provides an invalid argument, the server should respond with an INVALID_ARGUMENT error.

Example

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "http_error_code": {
        "canonical_name": "INVALID_ARGUMENT",
        "status": 400
    },
    "message": "invalid account number provided",
    "detail": "the account number '123456789' does not exist in our records"
}

Failed Precondition

When the operation is rejected due to a failed precondition, the server should respond with a FAILED_PRECONDITION error.

Example

{
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "http_error_code": {
        "canonical_name": "FAILED_PRECONDITION",
        "status": 400
    },
    "message": "insufficient funds",
    "detail": "the account '987654321' has insufficient funds for the transaction",
    "data": {
        "current_balance": 50.00,
        "required_balance": 100.00
    }
}

Unauthenticated

When the request lacks valid authentication credentials, the server should respond with an UNAUTHENTICATED error.

Example

{
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "http_error_code": {
        "canonical_name": "UNAUTHENTICATED",
        "status": 401
    },
    "message": "unauthorized access",
    "detail": "the provided credentials are invalid"
}

Unauthorized Access

Due to invalid JWK.

{
    "id": "b445b036-fd2e-4583-b4cc-61c2b8fb0b73",
    "http_error_code": {
        "canonical_name": "UNAUTHENTICATED",
        "status": 401
    },
    "message": "auth: verify: jwt: unknown kid"
}

Permission Denied

When the caller does not have permission to execute the specified operation, the server should respond with a PERMISSION_DENIED error.

Example

{
    "id": "d4e5f6a7-b8c9-0123-def4-567890123456",
    "http_error_code": {
        "canonical_name": "PERMISSION_DENIED",
        "status": 403
    },
    "message": "account locked",
    "detail": "the account '123456789' is locked due to multiple failed login attempts",
    "data": {
        "lock_duration": "24 hours"
    }
}

Not Found

When the requested resource is not found, the server should respond with a NOT_FOUND error.

Example

{
    "id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
    "http_error_code": {
        "canonical_name": "NOT_FOUND",
        "status": 404
    },
    "message": "transaction not found",
    "detail": "the transaction with id 'tx1234567890' was not found"
}

Validation Error

When the request contains invalid fields, the server should respond with an INVALID_ARGUMENT error and include validation details.

Example

{
    "id": "c30adf71-25c0-4a2b-a1f2-c3ee17efcd17",
    "http_error_code": {
        "canonical_name": "INVALID_ARGUMENT",
        "status": 400
    },
    "message": "validation failure",
    "detail": "fields were invalid",
    "validation": [
        {
            "field": "name",
            "value": "jo",
            "reason": "name must be at least 3 characters long"
        },
        {
            "field": "email",
            "value": "invalid@comcom",
            "reason": "email must be a valid email address"
        }
    ]
}

Internal Server Error

When an unexpected error occurs while processing the request, the server should respond with an INTERNAL error.

{
    "id": "f6a7b8c9-d0e1-2345-f678-901234567890",
    "http_error_code": {
        "canonical_name": "INTERNAL",
        "status": 500
    },
    "message": "server error",
    "detail": "an unexpected error occurred while processing the request"
}

Complex Error with Nested Data

When an error involves multiple nested errors, the server should provide detailed context for each part of the error message.

Example

{
    "id": "9f8b7c6d-4e5f-4a2b-8c3d-1e2f3a4b5c6d",
    "http_error_code": {
        "canonical_name": "FAILED_PRECONDITION",
        "status": 400
    },
    "message": "transaction failed: insufficient funds: daily withdrawal limit exceeded",
    "data": [
        {
            "message": "transaction failed",
            "data": {
                "transaction_id": "tx1234567890",
                "amount": 150.00,
                "currency": "USD"
            }
        },
        {
            "message": "insufficient funds",
            "data": {
                "account_id": "acc987654321",
                "current_balance": 50.00,
                "required_balance": 150.00
            }
        },
        {
            "message": "daily withdrawal limit exceeded",
            "data": {
                "account_id": "acc987654321",
                "daily_limit": 1000.00,
                "amount_attempted": 1500.00
            }
        }
    ]
}

In this example, the error message is composed of three parts:

transaction failed
insufficient funds
daily withdrawal limit exceeded

Each part of the error message has its own section of data, providing detailed context for each part of the error. This structure allows clients to understand the specific context and data related to each part of the error message, making it easier to debug and resolve issues.

Problem Details

The Problem Details RFC is a standardized format for representing errors in HTTP APIs. It defines a structured way to provide detailed information about errors in a machine-readable format, making it easier for clients to understand and handle errors effectively.

Example

{
    "status": 400,
    "title": "Insufficient Funds",
    "detail": "The account '987654321' has insufficient funds for the transaction.",
    "type": "https://example.com/probs/insufficient-funds",
    "instance": "/accounts/12345/transactions/67890",
    "extra_custom_key": "current_balance",
    "extra_custom_value": 50.00,
    "extra_custom_key2": "required_balance",
    "extra_custom_value2": 100.00
}

Differences Between HTTP Wire Errors and Problem Details

While both HTTP Wire Errors and Problem Details provide a structured way to represent errors in HTTP APIs, there are some key differences:

Flexibility: HTTP Wire Errors offer a more flexible structure that can include additional fields such as id, http_error_code, message, data, and validation. This allows for more detailed and context-specific error information.
Canonical Error Names: HTTP Wire Errors define a set of canonical error names that standardize common error scenarios, making it easier to categorize and handle errors consistently across different parts of an application.
Nested Data: HTTP Wire Errors support nested data structures, allowing for detailed context for each part of a complex error message. This is particularly useful for errors that involve multiple related issues.
Validation Errors: HTTP Wire Errors include a dedicated validation field to provide detailed information about validation errors, including the specific fields and reasons for the validation failure.

What Problem Details Were Missing

Problem Details (RFC 7807) provide a standardized format for representing errors, but they lack some features that are addressed by HTTP Wire Errors:

Canonical Error Names: Problem Details do not define a set of canonical error names, which can lead to inconsistencies in error categorization.
Nested Data: Problem Details do not natively support nested data structures, making it harder to provide detailed context for complex errors.
Validation Errors: Problem Details do not have a dedicated field for validation errors, which can make it harder to provide detailed information about validation issues.

How HTTP Wire Errors Provide a Solution

HTTP Wire Errors address these limitations by:

Defining a set of canonical error names for consistent error categorization.
Supporting nested data structures to provide detailed context for complex errors.
Including a dedicated validation field for detailed validation error information.

Author

Gerasimos Maropoulos is the author of the Iris web framework, a highly efficient and feature-rich web framework for the Go programming language. He is well-known in the programming community for his contributions to web development and his expertise in the Go language. Gerasimos has authored numerous online articles and tutorials that help developers understand and leverage the power of Go for building scalable and high-performance web applications. His work on Iris has made it one of the most popular web frameworks in the Go ecosystem, known for its simplicity, speed, and extensive feature set.

Gerasimos wrote this RFC to address the need for a standardized approach to handling and representing HTTP wire errors. By providing a clear and consistent structure for error responses, he aims to make it easier for developers to debug and understand the context of errors in their applications. This RFC is part of his ongoing efforts to improve the developer experience and ensure that applications built with Iris are robust and maintainable.

Conclusion

This RFC defines a standardized approach for handling and representing HTTP wire errors. By following this structure, developers can ensure consistent and clear error responses, making it easier for clients to understand and handle errors effectively.

HTTP Method Override

Gerasimos (Makis) Maropoulos — Fri, 08 Nov 2024 11:13:06 +0000

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:

Customizable Methods: Define which HTTP methods can be overridden.
Custom Headers: Specify custom headers to determine the method override.
Form Field Support: Use form fields to specify the method override.
Query Parameter Support: Use query parameters to specify the method override.
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 Headers option. 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 FormField option. 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 Query option. 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.

Request Body Limit Middleware for Iris

Gerasimos (Makis) Maropoulos — Fri, 01 Nov 2024 16:18:11 +0000

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.

Basic Authentication Middleware for Iris

Gerasimos (Makis) Maropoulos — Thu, 31 Oct 2024 10:10:55 +0000

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.

Request Rate Limiting Middleware for Iris

Gerasimos (Makis) Maropoulos — Wed, 30 Oct 2024 20:47:44 +0000

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:

Initialization: A bucket is initialized with a certain number of tokens.
Token Addition: Tokens are added to the bucket at a fixed rate.
Request Handling: Each request consumes a token. If the bucket is empty, the request is denied.
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.

AccessLog Middleware for Iris

Gerasimos (Makis) Maropoulos — Wed, 30 Oct 2024 18:30:20 +0000

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.

How to use hCAPTCHA with Iris

Gerasimos (Makis) Maropoulos — Fri, 14 Jul 2023 03:58:12 +0000

In this article, we will learn how to use hCAPTCHA with Iris, a web framework for Go that provides fast and easy development of web applications. hCAPTCHA is a service that protects websites from bots and spam by presenting challenges to human visitors. By using hCAPTCHA, we can ensure that only real users can access our website and prevent automated attacks.

What is hCAPTCHA?

hCAPTCHA is a service that provides a widget that can be embedded in any web page. The widget displays a challenge that requires human intelligence to solve, such as identifying objects in images or typing words. The widget communicates with the hCAPTCHA server and verifies if the user has passed the challenge or not. If the user passes the challenge, the widget generates a token that can be used to validate the user's request on the server side.

hCAPTCHA is similar to reCAPTCHA, another popular service that offers similar functionality. However, hCAPTCHA claims to have some advantages over reCAPTCHA, such as:

Better privacy: hCAPTCHA does not track users across websites or collect personal data.
Better performance: hCAPTCHA uses less resources and loads faster than reCAPTCHA.
Better rewards: hCAPTCHA pays website owners for using their service and supports various causes and charities.

How to use hCAPTCHA with Iris?

To use hCAPTCHA with Iris, we need to do two things:

Import the github.com/kataras/iris/v12/middleware/hcaptcha package, which provides an Iris middleware for hCAPTCHA.
Use the hcaptcha.New function to create an iris.Handler and register it in our Iris app.

First, we need to install the Iris Web Framework, which contains the middleware too:

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

Then, we need to import it in our main.go file:

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

Next, we need to use the hcaptcha.New function to create an iris.Handler. The function takes two arguments: a secret key and, optionally, one or more functions to configure the hCAPTCHA Client instance. The secret key is a string that we can obtain from the hCAPTCHA website after creating an account and registering our website. We'll register an error handler through the second article. The error handler (FailureHandler) is a function that handles any errors that may occur during the validation process.

We can use the following code to create the handler:

// Replace with your own secret key.
secret := "0x123456789abcdef"

// Create a hcaptcha middleware with the secret key and a custom error handler.
hcaptchaMiddleware := hcaptcha.New(secret, func(c *hcaptcha.Client) {
    c.FailureHandler = func(ctx iris.Context) {
        // Handle the error as you wish, for example:
        ctx.StopWithText(iris.StatusBadRequest, "hcaptcha verification failed: %v", err)
    }
})

The secret key can be found through: https://dashboard.hcaptcha.com. Please store it on a secure and private place. To test hCAPTCHA on a local environment please read the following instructions at: https://docs.hcaptcha.com/#localdev.

Finally, we need to register the hcaptcha middleware in our Iris app. We can use the app.UseRouter method to apply the middleware to all routes, or the app.Use/UseGlobal method to apply it to all non-error routes. For example:

// Create an Iris app instance.
app := iris.New()

// Apply the hcaptcha middleware to all non-error routes.
app.Use(hcaptchaMiddleware)

// Or apply the hcaptcha middleware to specific routes.
app.Get("/protected", hcaptchaMiddleware, func(ctx iris.Context) {
    // This route is protected by hcaptcha.
    ctx.WriteString("Hello, human!")
})

Conclusion

In this article, we have learned how to use basic hCAPTCHA middleware with Iris. For a more complete example please navigate through: https://github.com/kataras/iris/tree/master/_examples/auth/hcaptcha. By using these kind of features, we can create a more secure, user-friendly, and robust web application.

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

How to use JWT authentication with Iris

Gerasimos (Makis) Maropoulos — Sun, 09 Jul 2023 16:55:57 +0000

In this tutorial, we will learn how to use JWT (JSON Web Token) authentication with Iris, a fast and simple web framework for Go. JWT is a standard for securely transmitting information between parties as a JSON object. It can be used to authenticate users and protect API endpoints from unauthorized access.

Prerequisites

To follow this tutorial, you will need:

Go 1.20 or higher installed on your machine
A basic understanding of Go and Iris
A text editor or IDE of your choice (e.g. VS Code)

Creating a new Iris project

First, we will create a new Iris project using the go mod command. To do that, run the following commands:

$ mkdir iris-jwt
$ cd iris-jwt
$ go mod init iris-jwt
$ go get github.com/kataras/iris/v12@latest

This will create a new folder called iris-jwt with the following files:

iris-jwt
├── go.mod
└── go.sum

The go.mod file contains the module name and the dependency on Iris. The go.sum file contains the checksums of the dependencies.

Next, we will create a file called main.go in the same folder and write some basic code to start an Iris server on port 8080. We will modify this file later to add our JWT logic.

package main

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

func main() {
    // Create a new Iris application.
    app := iris.New()

    // Register a simple GET handler at the root path.
    app.Get("/", func(ctx iris.Context) {
        ctx.WriteString("Hello, world!")
    })

    // Start the server at http://localhost:8080.
    app.Listen(":8080")
}

To run the server, run the following command:

$ go run main.go

You should see something like this in your terminal:

Now listening on: http://localhost:8080
Application started. Press CTRL+C to shut down.

You can also visit http://localhost:8080 in your browser and see the message "Hello, world!".

Defining the user model and the JWT claims

Now, we will define a simple user model and a custom JWT claims struct in our main.go file. The user model will represent the data of our users, such as username and password. The JWT claims struct will contain the information that we want to store in our JWT tokens, such as user ID and expiration time.

We will also define some constants for our secret keys and token expiration durations.

package main

import (
    "time"

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

// User is a simple user model.
type User struct {
    ID       int64  `json:"id"`
    Username string `json:"username"`
    Password string `json:"password"`
}

// Claims is a custom JWT claims struct.
type Claims struct {
    jwt.Claims // embeds standard claims iat, exp and sub.
    UserID     int64  `json:"user_id"`
}

// Define some constants for our secret keys and token expiration durations.
const (
    accessSecret  = "my-access-secret"
    refreshSecret = "my-refresh-secret"
    accessExpire  = 15 * time.Minute
    refreshExpire = 24 * time.Hour
)

Creating a signer and a verifier for JWT

Next, we will create a signer and a verifier for JWT using the Iris middleware/jwt package. The signer will be used to generate and sign JWT tokens with our secret keys and claims. The verifier will be used to verify and validate JWT tokens from the client requests.

We will create two signers and one verifiers, one pair for the access token and one signer for the refresh token. We will also use encryption for our tokens to add an extra layer of security.

package main

import (
    "time"

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

// ...

// Create a signer for the access token.
accessSigner := jwt.NewSigner(jwt.HS256, accessSecret, accessExpire).
    // Use encryption for the access token.
    WithEncryption([]byte("my-access-encryption-key"), nil)

// Create a signer for the refresh token.
refreshSigner := jwt.NewSigner(jwt.HS256, refreshSecret, refreshExpire).
    // Use encryption for the refresh token.
    WithEncryption([]byte("my-refresh-encryption-key"), nil)

// Create a verifier for the access token.
accessVerifier := jwt.NewVerifier(jwt.HS256, accessSecret).
    // Use decryption for the access token.
    WithDecryption([]byte("my-access-encryption-key"), nil)
    // Use a blocklist to revoke tokens.
    // .WithDefaultBlocklist()

Creating some mock users and a login handler

For the sake of simplicity, we will create some mock users in a map and use them to simulate authentication. In a real application, you would use a database or another storage system to store and retrieve your users.

We will also create a login handler that will take a username and password from the client request, check if they match with one of our mock users, and if so, generate an access token and a refresh token for that user and send them back to the client.

package main

import (
    "time"

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

// ...

// Create some mock users in a map.
users := map[string]User{
    "alice": {ID: 1, Username: "alice", Password: "1234"},
    "bob":   {ID: 2, Username: "bob", Password: "5678"},
}

// Create a login handler that will generate JWT tokens for authenticated users.
loginHandler := func(ctx iris.Context) {
    // Get the username and password from the request body.
    var user User
    if err := ctx.ReadJSON(&user); err != nil {
        ctx.StopWithError(iris.StatusBadRequest, err)
        return
    }

    // Check if the username and password match with one of our mock users.
    if u, ok := users[user.Username]; !ok || u.Password != user.Password {
        ctx.StopWithStatus(iris.StatusUnauthorized)
        return
    }

    // Generate an access token with the user ID as the subject claim.
    accessClaims := Claims{
        Claims: jwt.Claims{Subject: u.Username},
        UserID: u.ID,
    }
    accessToken, err := accessSigner.Sign(accessClaims)
    if err != nil {
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }

    // Generate a refresh token with the user ID as the subject claim.
    refreshClaims := Claims{
        Claims: jwt.Claims{Subject: u.Username},
        UserID: u.ID,
    }
    refreshToken, err := refreshSigner.Sign(refreshClaims)
    if err != nil {
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }

    /* OR
    tokenPair, err := refreshSigner.NewTokenPair(accessClaims, refreshClaims, refreshExpire)
    // [handle err...]
    ctx.JSON(tokenPair)
    */

    // Send the tokens to the client as JSON.
    ctx.JSON(iris.Map{
        "access_token":  string(accessToken),
        "refresh_token": string(refreshToken),
        "expires_in":    int64(accessExpire.Seconds()),
    })
}

Creating a protected API handler

Next, we will create a protected API handler that will only allow authorized users to access it. We will use the access verifier as a middleware to verify and validate the access token from the client request. If the token is valid, we will extract the user ID from it and send it back to the client as JSON.

package main

import (
    "time"

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

// ...

// Create a protected API handler that will only allow authorized users to access it.
protectedHandler := func(ctx iris.Context) {
    // Get the verified token from the context.
    token := jwt.GetVerifiedToken(ctx) // important step.

    // Get the custom claims from the token.
    var claims Claims
    if err := token.Claims(&claims); err != nil { // important step.
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }

    // Get the user ID from the claims.
    userID := claims.UserID

    // Send the user ID to the client as JSON.
    // This is just an example, you can do whatever you want here.
    ctx.JSON(iris.Map{
        "user_id": userID,
    })
}

Creating a refresh handler

Finally, we will create a refresh handler that will allow users to refresh their access tokens using their refresh tokens. We will use the refresh verifier as a middleware to verify and validate the refresh token from the client request. If the token is valid, we will generate a new access token and a new refresh token for the same user and send them back to the client.

package main

import (
    "time"

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

// ...

// Create a refresh handler that will allow users to refresh their access tokens using their refresh tokens.
refreshHandler := func(ctx iris.Context) {
    // Get the verified token from the context.
    token := jwt.GetVerifiedToken(ctx)

    // Get the custom claims from the token.
    var claims Claims
    if err := token.Claims(&claims); err != nil {
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }

    // Get the user ID and username from the claims.
    userID := claims.UserID
    username := claims.Subject

    // Generate a new access token with the same user ID and username as the subject claim.
    accessClaims := Claims{
        Claims: jwt.Claims{Subject: username},
        UserID: userID,
    }
    accessToken, err := accessSigner.Sign(accessClaims)
    if err != nil {
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }

    // Generate a new refresh token with the same user ID and username as the subject claim.
    refreshClaims := Claims{
        Claims: jwt.Claims{Subject: username},
        UserID: userID,
    }
    refreshToken, err := refreshSigner.Sign(refreshClaims)
    if err != nil {
        ctx.StopWithError(iris.StatusInternalServerError, err)
        return
    }

    // Send the new tokens to the client as JSON.
    ctx.JSON(iris.Map{
        "access_token":  string(accessToken),
        "refresh_token": string(refreshToken),
        "expires_in":    int64(accessExpire.Seconds()),
    })
}

Registering the handlers and testing the application

Now that we have created all our handlers, we can register them with our Iris application and test our application. We will use the app.Post method to register our login, protected, and refresh handlers with different paths. We will also use the accessVerifier.Verify method to register our verifiers as middlewares for the rest of the protected handlers.

package main

import (
    "time"

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

// ...

func main() {
    // Create a new Iris application.
    app := iris.New()

    // Register our login handler at /login path.
    app.Post("/login", loginHandler)

    // Register a single protected handler at /protected path.
    // This handler verifies the request manually as we've seen above.
    app.Post("/protected", protectedHandler)

    // Register our refresh handler at /refresh path with refresh signer.
    app.Post("/refresh", refreshHandler)

    // You can also register the pre-defined jwt middleware for all protected routes
    // which performs verification automatically and set the custom Claims to the Context
    // for next handlers to use through: claims := jwt.Get(ctx).(*Claims).
    app.Use(accessVerifier.Verify(func() interface{} {
        return new(Claims)
    }))

    // [more routes...]

    // Start the server at http://localhost:8080.
    app.Listen(":8080")
}

To test our application, we can use a tool like curl or Postman to send HTTP requests to our server. Here are some examples of how to do that:

To login as Alice and get the access token and the refresh token, we can send a POST request to http://localhost:8080/login with the following JSON body:

{
    "username": "alice",
    "password": "1234"
}

We should get a response like this:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzYwNjQ3MzEsImlhdCI6MTYzNjA2MzIzMSwic3ViIjoiYWxpY2UiLCJ1c2VySWQiOjF9.8f7a7b8f7a7b8f7a7b8f7a7b8f7a7b8f7a7b8f7a7b8f7a7b8f7a7b8f",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzYxNTAzMzEsImlhdCI6MTYzNjA2MzIzMSwic3ViIjoiYWxpY2UiLCJ1c2VySWQiOjF9.9f8a8b9f8a8b9f8a8b9f8a8b9f8a8b9f8a8b9f8a8b9f8a8b9f8a8b9f",
    "expires_in": 900
}

To access the protected API endpoint with the access token, we can send a POST request to http://localhost:8080/protected with the following header:

Authorization: Bearer <access-token>

We should get a response like this:

{
    "user_id": 1
}

To refresh the access token with the refresh token, we can send a POST request to http://localhost:8080/refresh with the following header:

Authorization: Bearer <refresh-token>

We should get a response like this:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzYwNjQ4NTMsImlhdCI6MTYzNjA2MzM1Mywic3ViIjoiYWxpY2UiLCJ1c2VySWQiOjF9.9g7a7c9g7a7c9g7a7c9g7a7c9g7a7c9g7a7c9g7a7c9g7a7c9g7a7c9g",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzYxNTA0NTMsImlhdCI6MTYzNjA2MzM1Mywic3ViIjoiYWxpY2UiLCJ1c2VySWQiOjF9.aG8aBbaG8aBbaG8aBbaG8aBbaG8aBbaG8aBbaG8aBbaG8aBbaG8aBbaG",
    "expires_in": 900
}

Conclusion

In this tutorial, we learned how to use JWT authentication with Iris, a fast and simple web framework for Go. We learned how to create a signer and a verifier for JWT, how to generate and validate JWT tokens, how to protect an API endpoint with JWT, and how to refresh JWT tokens. We also learned how to use the Iris middleware/jwt package, which provides a common Iris handler for JWT authentication.

You can find the complete code for this tutorial on GitHub: https://github.com/kataras/iris/tree/master/_examples/auth/jwt/tutorial and https://github.com/kataras/jwt.

If you want to learn more about Iris, you can visit its official website: https://www.iris-go.com/

If you want to learn more about JWT, you can visit its official website: https://jwt.io/

I hope you enjoyed this tutorial and found it useful. Thank you for reading.😊

Rewrite: A Simple and Powerful URL Rewriter for Go

Gerasimos (Makis) Maropoulos — Sun, 09 Jul 2023 13:56:09 +0000

Rewrite is a Go package that lets you rewrite URL paths, subdomains or hosts based on regular expressions. It is inspired by Apache's mod_rewrite module and can be used as a middleware for net/http.

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:

Through code using the New function and Handler method. This way, you can handle parse errors and create rules programmatically.
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! 😊

How to use Iris and Basic authentication

Gerasimos (Makis) Maropoulos — Sat, 08 Jul 2023 12:15:21 +0000

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!

How to Use Iris and PostgreSQL for Web Development

Gerasimos (Makis) Maropoulos — Sun, 02 Jul 2023 11:59:49 +0000

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:

Import the package in your code:

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

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

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.

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.

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.

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.

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:

Clone the PG middleware repository and navigate to the _examples/basic folder.
Install the dependencies using go mod tidy.
Start a PostgreSQL server and create a database named test_db.
Run the main.go file using go run main.go.
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.

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!🙏

DEV Community: Gerasimos (Makis) Maropoulos

Introducing llms.txt — AI Transparency for the Iris Web Framework

Why Transparency Matters in AI

What’s Inside llms.txt

Use Cases We’re Exploring

Built for Developers, With Developers

A Living Document

Join the Conversation

RFC: HTTP Wire Errors

Overview

Error Response Structure

Example

Canonical Error Names

Error Handling

Invalid Argument

Example

Failed Precondition

Example

Unauthenticated

Example

Unauthorized Access

Permission Denied

Example

Not Found

Example

Validation Error

Example

Internal Server Error

Complex Error with Nested Data

Example

Problem Details

Example

Differences Between HTTP Wire Errors and Problem Details

What Problem Details Were Missing

How HTTP Wire Errors Provide a Solution

Author

Conclusion

HTTP Method Override

Introduction

Features of Iris Method Override Middleware

Installation

Usage

Basic Setup

Customizable Methods

Custom Headers

Form Field Support

Query Parameter Support

Save Original Method

Example

Conclusion

Request Body Limit Middleware for Iris

Overview

Why Use Body Limit Middleware?

Security

Performance

Resource Management

Installation

Usage

Basic Setup

Explanation

Testing Handlers with BodyLimit Middleware

Conclusion

Basic Authentication Middleware for Iris

Overview

Installation

Features

Authentication Function

User Structure (Helper)

In-Memory User Storage

Basic Setup

Using a File for User Storage

BCRYPT Option

Using a Database for User Storage

Custom Error Handling

Session Expiration

Garbage Collection

Testing Handlers with BasicAuth Middleware

Example

Conclusion

Request Rate Limiting Middleware for Iris

What’s Inside `llms.txt`

Using `rate.Every` Helper