### Basic Runa Application Setup

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/index.mdx

This is a basic example of how to set up a Runa application. It demonstrates installing route and cache providers and defining a simple HTTP GET route.

```go
func main() {
    app := runa.New()
    app.Install(
        route.Provider(route.Addr(":8080")),
        cache.Provider(),
    )

    route.Default().Get("/", func(c *route.Context) error {
        return c.Text("Hello Runa")
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Full Application Setup with JSON-RPC Provider

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/jsonrpc.mdx

This example demonstrates a complete `runa` application setup, including defining input/output structs, creating a JSON-RPC server, registering a method, and installing the JSON-RPC provider with a specific HTTP path.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/jsonrpc"
    "github.com/duxweb/runa/route"
)

type AddInput struct {
    A int `json:"a"`
    B int `json:"b"`
}

type AddOutput struct {
    Sum int `json:"sum"`
}

func main() {
    server := jsonrpc.New()
    jsonrpc.Method[AddInput, AddOutput](server, "math.add", func(ctx *jsonrpc.Context, input *AddInput) (*AddOutput, error) {
        return &AddOutput{Sum: input.A + input.B}, nil
    })

    app := runa.New()
    app.Install(
        route.Provider(route.Addr(":8080")),
        jsonrpc.Provider(server, jsonrpc.Path("/rpc")),
    )

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Sanitizer Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/toolkit/index.mdx

Example of how to install the `sanitize` toolkit module using `go get`. This is the typical first step before importing it into your project.

```bash
go get github.com/duxweb/runa/sanitize
```

--------------------------------

### Quick Start: Basic HTTP Server with Runa

Source: https://github.com/duxweb/runa/blob/main/README.md

Sets up a new Runa application, installs the route provider on port 8080, defines a root GET endpoint, and runs the application. Requires Go 1.27rc1 or later.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/route"
)

func main() {
    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")))

    route.Default().Get("/", func(ctx *route.Context) error {
        return ctx.JSON(runa.Map{"message": "Hello Runa"})
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Core and Capabilities

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/index.mdx

Install the Runa core and specific capabilities using go get.

```bash
go get github.com/duxweb/runa github.com/duxweb/runa/cache github.com/duxweb/runa/queue
```

--------------------------------

### Install Observe Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/observe.mdx

Install the observe package using go get.

```bash
go get github.com/duxweb/runa/observe
```

--------------------------------

### Install Storage Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/storage.mdx

Install the main storage package using go get.

```bash
go get github.com/duxweb/runa/storage
```

--------------------------------

### Install Auth Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/auth.mdx

Install the main auth package using go get.

```bash
go get github.com/duxweb/runa/auth
```

--------------------------------

### Install Database Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/database.mdx

Install the main database module using go get.

```bash
go get github.com/duxweb/runa/database
```

--------------------------------

### Install Devtools

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/toolkit/devtools.mdx

Install the devtools package using go get.

```bash
go get github.com/duxweb/runa/devtools
```

--------------------------------

### Install View Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/view.mdx

Install the view package using go get.

```bash
go get github.com/duxweb/runa/view
```

--------------------------------

### Complete Session Management Example

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/session.mdx

A full example demonstrating session setup, middleware usage, saving data to the session, and running the application. It includes session registration with custom cookie name and TTL.

```go
package main

import (
    "context"
    "time"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/route"
    "github.com/duxweb/runa/session"
    sessionmw "github.com/duxweb/runa/session/middleware"
)

func main() {
    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")))
    app.Install(session.Provider(
        session.RegisterSession("web",
            session.CookieName("__Host-runa_session"),
            session.TTL(2*time.Hour),
        ),
    ))

    route.Default().Use(sessionmw.Use("web"))
    route.Default().Get("/", func(ctx *route.Context) error {
        sess := ctx.Locals("runa.session.web").(*session.Session)
        sess.Set("name", "Runa")
        return ctx.Text("saved")
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Queue Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/queue.mdx

Install the main queue package using go get.

```bash
go get github.com/duxweb/runa/queue
```

--------------------------------

### Install Task Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/task.mdx

Install the task module using go get.

```bash
go get github.com/duxweb/runa/task
```

--------------------------------

### Complete Security Preset Example

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/security.mdx

A comprehensive example demonstrating the setup and usage of the Runa security preset with custom configurations for body limit, timeout, trusted proxies, and skipped paths.

```go
package main

import (
    "context"
    "time"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/route"
    "github.com/duxweb/runa/security"
)

func main() {
    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")))

    route.Default().Use(
        security.New(
            security.Production(),
            security.BodyLimit("16MB"),
            security.Timeout(30*time.Second),
            security.TrustedProxies("10.0.0.0/8"),
            security.SkipPaths("/health", "/metrics"),
        ),
    )

    route.Default().Get("/", func(ctx *route.Context) error {
        return ctx.Text("ok")
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Asset and View Modules

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/asset.mdx

Install the asset and view modules using go get. The asset module reuses view.Source for file descriptions.

```bash
go get github.com/duxweb/runa/asset github.com/duxweb/runa/view
```

--------------------------------

### Register and Run a Business Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/module.mdx

Instantiate the Runa application, install necessary providers, register your custom module, and then run the application. This demonstrates the typical setup for an application using business modules.

```go
app := runa.New()
app.Install(
    route.Provider(route.Addr(":8080")),
    cache.Provider(),
)

app.Module(UserModule{})

if err := app.Run(context.Background()); err != nil {
    panic(err)
}
```

--------------------------------

### Install Runa Modules

Source: https://github.com/duxweb/runa/blob/main/README.md

Use 'go get' to install the core Runa module and the route capability.

```bash
go get github.com/duxweb/runa
go get github.com/duxweb/runa/route
```

--------------------------------

### Install Console Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/console.mdx

Install the console package using go get.

```bash
go get github.com/duxweb/runa/console
```

--------------------------------

### Redis Driver Setup with App Install

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/queue.mdx

Install the queue and Redis driver providers, configuring the queue to use Redis and setting Redis connection details.

```go
import (
    queueredis "github.com/duxweb/runa/queue/redis"
)

app.Install(
    queue.Provider(
        queue.RegisterQueue("default", queue.Use("redis"), queue.Workers("default")),
        queue.RegisterWorker("default", queue.Concurrency(4)),
    ),
    queueredis.Provider(queueredis.Addr("127.0.0.1:6379"), queueredis.Prefix("runa:queue:")),
)
```

--------------------------------

### Install RBAC Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/toolkit/rbac.mdx

Install the RBAC package using go get.

```bash
go get github.com/duxweb/runa/rbac
```

--------------------------------

### Install Runa Route Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/index.mdx

Install the Runa route package using go get. If the kernel is not installed, install both.

```bash
go get github.com/duxweb/runa/route
```

```bash
go get github.com/duxweb/runa github.com/duxweb/runa/route
```

--------------------------------

### Initialize Project and Install Dependencies

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/quick-start-http.mdx

Sets up a new Go project and installs the necessary Runa packages for HTTP routing.

```bash
mkdir runa-demo
cd runa-demo
go mod init example.com/runa-demo
go get github.com/duxweb/runa github.com/duxweb/runa/route
```

--------------------------------

### Basic Session Middleware Setup

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/session.mdx

Install the session provider and then use the session middleware for a specific named session. The default name is 'web'.

```go
app.Install(session.Provider(
    session.RegisterSession("web"),
))

route.Default().Use(sessionmw.Use("web"))
```

--------------------------------

### Install Oro ORM and Runa Database Driver

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/drivers/database-oro.mdx

Install the necessary Runa database packages and the Oro ORM driver using go get. SQLite examples also require a concrete SQL driver.

```bash
go get github.com/duxweb/runa/database github.com/duxweb/runa/database/oro
```

```bash
go get modernc.org/sqlite
```

--------------------------------

### Install Cache Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/cache.mdx

Install the main cache package using go get.

```bash
go get github.com/duxweb/runa/cache
```

--------------------------------

### Install Runa Session Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/session.mdx

Install the session package using go get. If using cache-backed sessions, also install and connect the cache package.

```bash
go get github.com/duxweb/runa/session
```

```bash
go get github.com/duxweb/runa/cache github.com/duxweb/runa/session
```

--------------------------------

### Install Schedule and Task Packages

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/schedule.mdx

Install the schedule and task packages using go get. These are the core components for scheduling and executing tasks.

```bash
go get github.com/duxweb/runa/schedule github.com/duxweb/runa/task
```

--------------------------------

### Install Resource Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/rest.mdx

Install the resource package using go get. This is a route-registration helper and not a Provider.

```bash
go get github.com/duxweb/runa/resource
```

--------------------------------

### Install Cluster Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/cluster.mdx

Install the main cluster module using go get.

```bash
go get github.com/duxweb/runa/cluster
```

--------------------------------

### Use the global default application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/app.mdx

For smaller projects, you can use the global default application instance to install capabilities and register modules, simplifying the setup.

```go
runa.Install(route.Provider(route.Addr(":8080")))
runa.Module(user.Module{})

if err := runa.Run(context.Background()); err != nil {
    panic(err)
}
```

--------------------------------

### Install Runa Log Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/log.mdx

Install the Runa log package using go get.

```bash
go get github.com/duxweb/runa/log
```

--------------------------------

### Install Auth Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/auth.mdx

Install the auth package using go get. For HTTP middleware, also install the session package.

```bash
go get github.com/duxweb/runa/auth
```

```bash
go get github.com/duxweb/runa/auth github.com/duxweb/runa/session
```

--------------------------------

### Start the Runa application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/app.mdx

Run the application, which typically starts the default 'serve' command if no arguments are provided. This command starts registered Host units, such as the HTTP server.

```go
if err := app.Run(context.Background()); err != nil {
    panic(err)
}
```

--------------------------------

### Minimal HTTP Route Setup

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/index.mdx

Demonstrates the basic setup for an HTTP route transport. It involves creating a new Runa app, installing the route provider with a specified address, freezing the app to enable handler registration, defining a default route, and finally running the application.

```go
app := runa.New()
app.Install(route.Provider(route.Addr(":8080")))

app.Freeze(context.Background())

route.Default().Get("/", func(ctx *route.Context) error {
    return ctx.Text("ok")
})

app.Run(context.Background())
```

--------------------------------

### Install Runa Rate Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/rate.mdx

Install the main Runa rate package using go get.

```bash
go get github.com/duxweb/runa/rate
```

--------------------------------

### Install Runa Validate Toolkit

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/validation.mdx

Install the Runa validation toolkit using go get.

```bash
go get github.com/duxweb/runa/validate
```

--------------------------------

### Install Runa Middleware

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/builtin.mdx

Use `go get` to install the Runa middleware package. This command fetches the necessary middleware components for your project.

```bash
go get github.com/duxweb/runa/middleware
```

--------------------------------

### Complete Recover Middleware Example

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/recover.mdx

A full example demonstrating the integration of the recover middleware in a Runa application. This includes setting up the application, installing the route provider, applying the recover middleware, and defining a handler that triggers a panic.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/middleware/recover"
    "github.com/duxweb/runa/route"
)

func main() {
    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")))

    route.Default().Use(recover.New())
    route.Default().Get("/panic", func(ctx *route.Context) error {
        panic("something broken")
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Runa Lock Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/lock.mdx

Install the Runa lock package using go get.

```bash
go get github.com/duxweb/runa/lock
```

--------------------------------

### Install OpenAPI Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/openapi.mdx

Install the OpenAPI package using go get. It's recommended to also install the route package as OpenAPI relies on route metadata.

```bash
go get github.com/duxweb/runa/openapi


```

```bash
go get github.com/duxweb/runa/route
```

--------------------------------

### Minimal Runa Application with Security Middleware

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/index.mdx

A minimal example of setting up a Runa application, installing the route provider, and applying the production security middleware globally.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/route"
    "github.com/duxweb/runa/security"
)

func main() {
    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")))

    route.Default().Use(security.New(security.Production()))
    route.Default().Get("/", func(ctx *route.Context) error {
        return ctx.Text("ok")
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Accessing Capabilities (Cache Example)

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/context.mdx

Handles GET requests to /cache, retrieves a string cache store, gets a value by key, and returns it. This demonstrates accessing capabilities like caches via their default instances.

```go
route.Default().Get("/cache", func(ctx *route.Context) error {
    store := cache.Default().MustOf[string]("default")
    value, ok, err := store.Get(ctx.Context(), "hello")
    if err != nil {
        return err
    }
    if !ok {
        return ctx.Status(404).Text("cache not found")
    }
    return ctx.Text(value)
})
```

--------------------------------

### Install OroStore Driver

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/drivers/crud-orostore.mdx

Install the OroStore driver and its dependencies using go get. If Runa manages the database lifecycle, also install the database and oro packages.

```bash
go get github.com/duxweb/runa/crud github.com/duxweb/runa/crud/orostore
```

```bash
go get github.com/duxweb/runa/database github.com/duxweb/runa/database/oro
```

```bash
go get modernc.org/sqlite
```

--------------------------------

### Install On-Demand Capabilities

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/installation.mdx

Install additional Runa capabilities like cache, queue, database, and storage as needed.

```bash
go get github.com/duxweb/runa/cache
go get github.com/duxweb/runa/queue
go get github.com/duxweb/runa/database
go get github.com/duxweb/runa/storage
```

--------------------------------

### Install Audit Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/audit.mdx

Install the audit package using go get. Additional packages like queue or log can be installed if needed for specific writing destinations.

```bash
go get github.com/duxweb/runa/audit
```

```bash
go get github.com/duxweb/runa/queue github.com/duxweb/runa/log
```

--------------------------------

### Check Go Installation

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/installation.mdx

Verify that Go is installed on your system.

```bash
go version
```

--------------------------------

### Install Audit Middleware

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/audit.mdx

Install the audit middleware package using go get. If audit records need to be written to Runa log channels, also install the log package.

```bash
go get github.com/duxweb/runa/audit
```

```bash
go get github.com/duxweb/runa/log
```

--------------------------------

### Redis Driver Setup with Shared Config

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/queue.mdx

Install the queue and Redis driver providers, using a shared Redis configuration name and setting a custom prefix.

```go
app.Install(
    queue.Provider(
        queue.RegisterQueue("default", queue.Use("redis"), queue.Workers("default")),
        queue.RegisterWorker("default", queue.Concurrency(4)),
    ),
    queueredis.Provider(queueredis.Use("default"), queueredis.Prefix("runa:queue:")),
)
```

--------------------------------

### Install Business Middleware Capabilities

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/business.mdx

Installs the necessary Runa capabilities for session, authentication, rate limiting, and auditing. Install only the capabilities that your application uses.

```bash
go get github.com/duxweb/runa/session github.com/duxweb/runa/auth github.com/duxweb/runa/rate github.com/duxweb/runa/audit
```

--------------------------------

### Connect Log to Runa Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/log.mdx

Integrate the log package into a Runa application by installing the provider. This example registers a console logger for 'default' and a file logger for 'queue'.

```go
package main

import (
    "context"
    "log/slog"

    "github.com/duxweb/runa"
    runalog "github.com/duxweb/runa/log"
)

func main() {
    app := runa.New()
    app.Install(runalog.Provider(
        runalog.Register("default", runalog.Console(runalog.Pretty(), runalog.Level(slog.LevelInfo))),
        runalog.Register("queue", runalog.File("data/logs/queue.log", runalog.JSON()))
    ))

    if err := app.Freeze(context.Background()); err != nil {
        panic(err)
    }

    runalog.Default().Get("queue").Info("queued")
}
```

--------------------------------

### Integrate WebSocket Hub into Runa Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/websocket.mdx

Set up a Runa application, create a WebSocket hub, register an 'echo' event handler, install the route and WebSocket providers, and expose the hub via a GET route.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/route"
    "github.com/duxweb/runa/ws"
)

func main() {
    hub := ws.New("default", ws.Config{})
    hub.On("echo", func(ctx *ws.Context) error {
        return ctx.Reply(runa.Map{"data": ctx.Message().Data})
    })

    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")), ws.Provider(hub))

    route.Default().Get("/ws", hub.Serve).SkipDoc()

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Initialize Go Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/installation.mdx

Create a new project directory and initialize a Go module. Replace `example.com/runa-demo` with your project's path.

```bash
mkdir runa-demo
cd runa-demo
go mod init example.com/runa-demo
```

--------------------------------

### Build Project Documentation

Source: https://github.com/duxweb/runa/blob/main/CONTRIBUTING.md

Navigate to the docs directory, install dependencies, and build the documentation.

```bash
cd docs
pnpm install
pnpm build
```

--------------------------------

### Install WebSocket and Route Packages

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/websocket.mdx

Install the core WebSocket and route packages. Redis horizontal scaling is optional and installed separately.

```bash
go get github.com/duxweb/runa/ws github.com/duxweb/runa/route
```

```bash
go get github.com/duxweb/runa/ws/redis
```

--------------------------------

### Complete Example with Show Action

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/rest.mdx

A complete example demonstrating the creation of a resource and the registration of a 'Show' action. This includes defining input and output structures.

```go
type ShowInput struct {
    ID string `param:"id"`
}

type UserOutput struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

users := resource.New(route.Default().Group("/admin"), "/users").
    Name("user").
    Summary("User").
    Tags("User")

users.Show[ShowInput, UserOutput](func(ctx *route.Context, input *ShowInput) (*UserOutput, error) {
    return &UserOutput{ID: input.ID, Name: "Runa"}, nil
})
```

--------------------------------

### Install Production Security Preset

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/index.mdx

Install the production preset when you want the standard security chain.

```bash
go get github.com/duxweb/runa/security
```

--------------------------------

### Set up Local Development Environment

Source: https://github.com/duxweb/runa/blob/main/CONTRIBUTING.md

Clone the repository, sync the Go workspace, and run initial tests. Ensure you are using Go 1.27rc1.

```bash
git clone https://github.com/duxweb/runa.git
cd runa
go work sync
go test ./...
```

--------------------------------

### Install Runa Kernel and Route

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/installation.mdx

Install both the Runa kernel and the `route` capability for a minimal HTTP application.

```bash
go get github.com/duxweb/runa github.com/duxweb/runa/route
```

--------------------------------

### Install Event Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/event.mdx

Use this command to install the event package for your Go project.

```bash
go get github.com/duxweb/runa/event
```

--------------------------------

### Install Lang and View Providers for Templates

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/lang.mdx

Install the `lang.Provider()`, `view.Provider()`, and `langview.Provider()` to enable `{{ t "key" }}` syntax in templates.

```go
import langview "github.com/duxweb/runa/lang/view"

app.Install(
    lang.Provider(),
    view.Provider(),
    langview.Provider(),
)
```

--------------------------------

### Connect Observe to an Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/observe.mdx

Installs the route and observe providers, configuring the observe service with a name, environment, and mount path. The application is then run.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/observe"
    "github.com/duxweb/runa/route"
)

func main() {
    app := runa.New()
    app.Install(
        route.Provider(route.Addr(":8080")),
        observe.Provider(observe.Config{Service: "api", Env: "dev", Mount: "/-"}),
    )

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Console Configuration Example

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/console.mdx

Example TOML configuration for the console, specifying title, mount path, authentication, and performance thresholds.

```toml
[console]
title = "Runa Console"
mount = "/_console"
auth = ["web"]
interval = "5s"
slow_threshold = "300ms"
collect_http = true
sample_interval = "1s"
```

--------------------------------

### Application Entrypoint - main.go

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/project-layout.mdx

The main.go file should only assemble the application, installing providers and modules. Avoid placing handler logic or business details here.

```go
package main

import (
    "context"

    "example.com/my-app/app/order"
    "example.com/my-app/app/user"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/cache"
    "github.com/duxweb/runa/route"
)

func main() {
    app := runa.New(
        runa.ConfigPath("config"),
        runa.DataPath("data"),
        runa.PublicPath("public"),
    )
    app.Install(
        route.Provider(route.Addr(":8080")),
        cache.Provider(),
    )
    app.Module(
        user.Module{},
        order.Module{},
    )

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Create a New Resource

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/rest.mdx

Create a new resource instance, defining its base path and metadata like name, summary, and tags. This example creates a '/users' resource under the '/admin' group.

```go
users := resource.New(route.Default().Group("/admin"), "/users").
    Name("user").
    Summary("User").
    Tags("User")
```

--------------------------------

### Connect Console to Runa Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/console.mdx

Install the console provider with route and console configurations. Open the console at http://localhost:8080/_console.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/console"
    "github.com/duxweb/runa/route"
)

func main() {
    app := runa.New()
    app.Install(
        route.Provider(route.Addr(":8080")),
        console.Provider(console.MountAt("/_console"), console.Title("Runa Console")),
    )

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Runa CRUD Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/routing/crud.mdx

Install the core Runa CRUD package using go get.

```bash
go get github.com/duxweb/runa/crud
```

--------------------------------

### Install External Drivers with Go Get

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/index.mdx

Use `go get` to install specific driver modules for external dependencies like Redis or S3. These modules are only included in your project's dependency graph if they are imported and used.

```bash
go get github.com/duxweb/runa/cache/redis github.com/duxweb/runa/storage/s3
```

--------------------------------

### Connect Lang Provider to Runa Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/lang.mdx

Install the `lang.Provider()` to register the `*lang.Registry` and load message catalogs from `config/lang/*.toml`.

```go
app := runa.New()
app.Install(lang.Provider())
```

--------------------------------

### Install Message Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/message.mdx

Install the core message module using go get. This is the base package for pub/sub functionality.

```bash
go get github.com/duxweb/runa/message
```

--------------------------------

### Create and Load a Session

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/session.mdx

Demonstrates how to create a new session registry, register a 'web' session with specific options, and then load an existing session. Use this to initialize session handling and retrieve session data.

```go
registry := session.New()
registry.Session("web", session.CookieName("sid"), session.TTL(time.Hour))

sess, err := registry.Load(context.Background(), "web", "", func(name string, value string, options session.CookieOptions) {
    _ = name
    _ = value
})
if err != nil {
    panic(err)
}
_ = sess.Set("user_id", "1")
_ = sess.Save(context.Background())
```

--------------------------------

### Connect Capabilities to Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/index.mdx

Connect installed capabilities to a new Runa application instance and run it.

```go
app := runa.New()
app.Install(
    cache.Provider(),
    queue.Provider(),
)

if err := app.Run(context.Background()); err != nil {
    panic(err)
}
```

--------------------------------

### Install framework capabilities

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/app.mdx

Install framework capabilities like routing, caching, and queuing providers into the application. These capabilities become available through dependency injection, configuration, commands, and the application lifecycle.

```go
app.Install(
    route.Provider(route.Addr(":8080")),
    cache.Provider(),
    queue.Provider(),
)
```

--------------------------------

### Install Redis Cache Extension

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/index.mdx

Install the official Redis cache driver and its dependencies using go get. This is a prerequisite for connecting the Redis cache to your application.

```bash
go get github.com/duxweb/runa/cache github.com/duxweb/runa/cache/redis
```

--------------------------------

### Recommended Starter Middleware Chain

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/builtin.mdx

Mount a chain of essential built-in middleware for a new HTTP service. This example includes recovery, request ID, real IP, logging, body limit, timeout, and security headers. Configure specific middleware like `realip` and `logger` with custom settings as needed.

```go
route.Default().Use(
    recover.New(),
    requestid.New(),
    realip.New(realip.Config{TrustedProxies: []string{"10.0.0.0/8"}}),
    logger.New(logger.Config{SkipPaths: []string{"/health"}}),
    bodylimit.New(bodylimit.Config{Limit: 16 << 20}),
    timeout.New(timeout.Config{Timeout: 30 * time.Second}),
    helmet.New(),
)
```

--------------------------------

### Connect Storage to Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/storage.mdx

Register and configure storage disks within a Runa application. This example registers a 'public' disk and demonstrates putting a string to it.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/storage"
)

func main() {
    app := runa.New()
    app.Install(storage.Provider(
        storage.RegisterDisk("public", storage.Prefix("public"), storage.Public()),
    ))

    if err := app.Freeze(context.Background()); err != nil {
        panic(err)
    }

    disk := storage.Default().MustOf("public")
    _ = disk.PutString(context.Background(), "hello.txt", "Hello Runa", storage.ContentType("text/plain"))
}
```

--------------------------------

### Read Dependencies After Startup using Default()

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/di.mdx

After the Runa application has started, use the child package's `Default()` helper to access dependencies.

```go
store := cache.Default().MustOf[string]("default")
```

--------------------------------

### Create a Kernel-Only Runa Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/index.mdx

This snippet shows the basic setup for a Runa application that includes only the kernel, config, commands, and lifecycle orchestration. It's suitable for applications that do not require external network entrypoints like HTTP.

```go
app := runa.New()
if err := app.Run(context.Background()); err != nil {
    panic(err)
}
```

--------------------------------

### Create a Runa application with common options

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/core/app.mdx

Configure the application with common options such as base path, configuration path, data path, public path, and environment.

```go
app := runa.New(
    runa.BasePath("."),
    runa.ConfigPath("config"),
    runa.DataPath("data"),
    runa.PublicPath("public"),
    runa.Env("production"),
)
```

--------------------------------

### Get Instance Information

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/cluster.mdx

Retrieve the current instance information and a list of all registered instances from the cluster registry. Ensure the cluster module is installed and configured.

```go
registry := cluster.Default()
current := registry.Instance()
items, err := registry.Instances(context.Background())
_ = current
_ = items
_ = err
```

--------------------------------

### Middleware Execution Order Example

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/index.mdx

Demonstrates the execution order of middleware. Middleware enters in registration order and exits in reverse order.

```go
route.Default().Use(A(), B(), C())
```

--------------------------------

### List Available Databases

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/database.mdx

Use this command to list all configured databases. Ensure the database provider is installed.

```bash
go run . database:list
```

--------------------------------

### Business Module Registration

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/project-layout.mdx

Business modules register routes, commands, and other declarations during the Register phase. This example shows a user module registering a GET route and a command.

```go
package user

import (
    "context"

    "github.com/duxweb/runa/provider"
    "github.com/duxweb/runa/route"
)

type Module struct {
    provider.ModuleBase
}

func (Module) Name() string { return "user" }

func (Module) Register(ctx context.Context, app provider.Context) error {
    route.Default().Get("/", home)
    return app.RegisterCommand(SyncUsersCommand{})
}
```

--------------------------------

### Standalone Storage Registry

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/storage.mdx

Create and use a storage registry independently of the Runa application framework. This example sets a root directory and URL prefix, then puts and gets a string.

```go
registry := storage.New(storage.Root("./data/storage"), storage.DriverURLPrefix("/files"))
disk := registry.MustOf(storage.DiskPublic)

_ = disk.PutString(context.Background(), "hello.txt", "Hello", storage.ContentType("text/plain"))
body, _ := disk.GetString(context.Background(), "hello.txt")
_ = body
```

--------------------------------

### Install Transport Provider

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/index.mdx

This is the standard way a transport block connects to the Runa application. The Provider handles core object registration, command registration, Host setup, and lifecycle management.

```go
app.Install(transport.Provider(...))
```

--------------------------------

### Configure Redis Driver for Lock

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/lock.mdx

Install and configure the Redis driver for distributed locking within a Runa application. This example shows how to register both the lock provider with a Redis-specific prefix and the Redis driver itself with its address.

```go
import (
    lockredis "github.com/duxweb/runa/lock/redis"
)

app.Install(
    lock.Provider(lock.RegisterLocker("default", lock.Use("redis"), lock.Prefix("runa:lock:"))),
    lockredis.Provider(lockredis.Addr("127.0.0.1:6379")),
)
```

--------------------------------

### Minimal Project Structure

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/project-layout.mdx

For small projects with few routes, a simple structure with main.go and go.mod is sufficient.

```text
my-app/
  main.go
  go.mod
```

--------------------------------

### Install Route Provider Before Registering Routes

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/guide/installation.mdx

Ensure the route provider is installed before attempting to register routes to avoid the 'route provider is not installed' error.

```go
app.Install(route.Provider(route.Addr(":8080")))

route.Default().Get("/", func(ctx *route.Context) error {
    return ctx.Text("Hello Runa")
})
```

--------------------------------

### Observe Configuration Example

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/ops/observe.mdx

Example TOML configuration for the observe package, setting service, environment, version, timeout, mount path, and debug mode.

```toml
[observe]
service = "api"
env = "production"
version = "1.0.0"
timeout = "2s"
mount = "/-"
debug = false
```

--------------------------------

### Quick Usage: Production Defaults

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/toolkit/security.mdx

Install the security middleware with production defaults for a new route provider.

```go
app.Install(route.Provider(route.Addr(":8080")))
route.Default().Use(security.New(security.Production()))
```

--------------------------------

### Install RBAC with Auth

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/toolkit/rbac.mdx

Install both RBAC and Auth packages together.

```bash
go get github.com/duxweb/runa/auth github.com/duxweb/runa/rbac
```

--------------------------------

### Configure Console Output with JSON and Source

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/log.mdx

Install the log provider with a console output configured for JSON format and source code location tracking enabled.

```go
app.Install(runalog.Provider(
    runalog.Register("default", runalog.Console(runalog.JSON(), runalog.Source(true)))
))
```

--------------------------------

### Install Route Package

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/extending/middleware/index.mdx

Install the route package when you only need the middleware mechanism.

```bash
go get github.com/duxweb/runa/route
```

--------------------------------

### Install S3 Storage Driver

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/storage.mdx

Install the S3 driver for object storage integration.

```bash
go get github.com/duxweb/runa/storage/s3
```

--------------------------------

### Connect View to Runa Application

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/view.mdx

Connect the view provider and register a default HTML renderer for the 'web' domain. This example shows how to set up a basic Runa application with routing and view rendering.

```go
package main

import (
    "context"

    "github.com/duxweb/runa"
    "github.com/duxweb/runa/provider"
    "github.com/duxweb/runa/route"
    "github.com/duxweb/runa/view"
)

type appModule struct {
    provider.ModuleBase
}

func (appModule) Name() string { return "app" }

func (appModule) Register(ctx context.Context, app provider.Context) error {
    views, err := provider.Invoke[*view.Registry](app)
    if err != nil {
        return err
    }
    return views.Register(ctx, "web", view.HTML(view.Dir("views").Reload(true)))
}

func main() {
    app := runa.New()
    app.Install(route.Provider(route.Addr(":8080")), view.Provider())
    app.Module(appModule{})

    route.Default().Get("/", func(ctx *route.Context) error {
        return ctx.Render("index", runa.Map{"title": "Runa"}, "web")
    })

    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

--------------------------------

### Install Redis Cache Driver

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/cache.mdx

Install the Redis driver separately if needed for shared caching.

```bash
go get github.com/duxweb/runa/cache/redis
```

--------------------------------

### Creating and Installing a JSON-RPC Server

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/jsonrpc.mdx

Shows how to create a new JSON-RPC server and install it into the Runa application framework with HTTP and optional WebSocket support.

```APIDOC
## Creating and Installing a JSON-RPC Server

### Description
This example demonstrates the complete setup of a JSON-RPC server within the Runa application. It includes creating the server, registering a method, and installing the server provider into the application with a specific HTTP path and optional WebSocket path.

### Setup Steps
1. **Create Server**: Initialize a new JSON-RPC server instance.
2. **Register Methods**: Define and register methods that the server will handle.
3. **Install Provider**: Use `jsonrpc.Provider` to integrate the server into the Runa app, specifying paths.

### Code Example
```go
package main

import (
    "context"
    "github.com/duxweb/runa"
    "github.com/duxweb/runa/jsonrpc"
    "github.com/duxweb/runa/route"
)

type AddInput struct {
    A int `json:"a"`
    B int `json:"b"`
}

type AddOutput struct {
    Sum int `json:"sum"`
}

func main() {
    // 1. Create a new JSON-RPC server
    server := jsonrpc.New()

    // 2. Register a method
    jsonrpc.Method[AddInput, AddOutput](server, "math.add", func(ctx *jsonrpc.Context, input *AddInput) (*AddOutput, error) {
        return &AddOutput{Sum: input.A + input.B}, nil
    })

    app := runa.New()

    // 3. Install the JSON-RPC provider with HTTP and WebSocket paths
    app.Install(
        route.Provider(route.Addr(":8080")),
        jsonrpc.Provider(server, 
            jsonrpc.Path("/rpc"), // HTTP path for JSON-RPC requests
            jsonrpc.WSPath("/rpc/ws", jsonrpc.Origin("http://localhost:3000")) // WebSocket path and origin restriction
        ),
    )

    // Run the application
    if err := app.Run(context.Background()); err != nil {
        panic(err)
    }
}
```

### Client Call Example (HTTP)
```bash
curl -X POST http://localhost:8080/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"math.add","params":{"a":2,"b":3},"id":1}'
```

### Client Response Example (HTTP)
```json
{"jsonrpc":"2.0","result":{"sum":5},"id":1}
```
```

--------------------------------

### Install Runa Lock Redis Driver

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/capabilities/lock.mdx

Install the Redis driver for distributed locking when needed.

```bash
go get github.com/duxweb/runa/lock/redis
```

--------------------------------

### Install gRPC Module

Source: https://github.com/duxweb/runa/blob/main/docs/src/content/docs/transports/grpc.mdx

This indicates that the gRPC package is not yet available for installation. Do not attempt to import it.

```text
No package exists today
```