Xitrum

https://github.com/xitrum-framework/xitrum
Admin
Xitrum is an async and clustered Scala web framework built on Netty, Akka, and Hazelcast with a fast...
Tokens:14,213
Snippets:102
Trust Score:6.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start and Stop Xitrum Server

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates how to start and stop the Xitrum HTTP(S) server. Includes default startup, custom channel initializer, and graceful shutdown procedures.

```Scala
import xitrum.Server

object Boot {
  def main(args: Array[String]): Unit = {
    // Start with default channel initializer
    Server.start()

    // Register shutdown hook for graceful stop
    Server.stopAtShutdown()
  }
}

// Or with custom channel initializer
import xitrum.handler.DefaultHttpChannelInitializer
Server.start(new DefaultHttpChannelInitializer)

// Manual stop (call from separate thread)
Server.stop()
```

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

### Server Configuration Flexibility

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This snippet details the ability to start the server with a custom Netty ChannelPipelineFactory, allowing for more flexible server configurations.

```Scala
// Allow starting server with custom Netty ChannelPipelineFactory; for an example, see xitrum.handler.DefaultHttpChannelPipelineFactory
```

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

### Implementing Filters in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Illustrates the use of before, after, and around filters in Xitrum for executing code at different stages of action processing. Provides examples for authentication, logging, and performance timing, demonstrating trait-based composition.

```Scala
import xitrum.Action
import xitrum.annotation.GET

trait AuthenticatedAction extends Action {
  beforeFilter {
    sessiono[Int]("userId") match {
      case Some(_) => // Continue to action
      case None =>
        redirectTo[LoginPage]()
        // Filter returns Unit, but redirect stops further processing
    }
  }
}

trait LoggingAction extends Action {
  beforeFilter {
    log.info(s"Request: ${request.method} ${request.uri}")
  }

  afterFilter {
    log.info(s"Response: ${response.status}")
  }
}

trait TimingAction extends Action {
  aroundFilter { execute =>
    val start = System.currentTimeMillis()
    execute()  // Call the actual action
    val duration = System.currentTimeMillis() - start
    log.info(s"Action took ${duration}ms")
  }
}

@GET("protected/resource")
class ProtectedResource extends Action with AuthenticatedAction with LoggingAction {
  def execute(): Unit = {
    val userId = session("userId")
    respondJson(Map("userId" -> userId, "data" -> "secret"))
  }
}
```

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

### Route Collection and Controller Instantiation Improvements

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This covers enhancements to route collection, including support for getting cache annotations from superclasses and optimizations for controller instantiation using ReflectASM.

```Scala
// Route collecting: support getting cache annotation from superclasses
// Use ReflectASM (included by Twitter Chill) to initiate controllers faster
// Avoid error of instantiating abstract controller while collecting routes
```

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

### Implement Data-After Callback in HTML

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Example of using the data-after attribute to execute JavaScript snippets after a postback request completes.

```html
<button data-after="$('#chatInput').val('')">Submit</button>
```

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

### Generate Swagger API Documentation with Annotations (Scala)

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

This snippet demonstrates how to generate Swagger API documentation using annotations in Scala. It covers defining routes, parameters, request bodies, and responses for GET and POST requests. Dependencies include xitrum.Action and xitrum.annotation.Swagger. It handles various parameter types like path, query, and form, as well as JSON request bodies and array responses.

```scala
import xitrum.Action
import xitrum.annotation.{GET, POST, Swagger}
import xitrum.annotation.Swagger._

@GET("api/users/:id")
@Swagger(
  Tags("Users"),
  Summary("Get user by ID"),
  Description("Returns a single user"),
  StringPath("id", "User ID"),
  OptStringQuery("fields", "Comma-separated list of fields to return"),
  Response(200, "Successful response"),
  Response(404, "User not found")
)
class ApiUserShow extends Action {
  def execute(): Unit = {
    val id = param[String]("id")
    respondJson(Map("id" -> id, "name" -> "John Doe"))
  }
}

@POST("api/users")
@Swagger(
  Tags("Users"),
  Summary("Create a new user"),
  Consumes("application/json"),
  Produces("application/json"),
  StringForm("username", "Username"),
  StringForm("email", "Email address"),
  OptStringForm("bio", "User biography"),
  Response(201, "User created"),
  Response(400, "Invalid input")
)
class ApiUserCreate extends Action {
  def execute(): Unit = {
    val username = param[String]("username")
    respondJson(Map("id" -> 123, "username" -> username))
  }
}

// Swagger with JSON body type definition
case class CreateArticleRequest(title: String, body: String, tags: List[String])
case class ArticleResponse(id: Int, title: String, createdAt: Long)

@POST("api/articles")
@Swagger(
  Tags("Articles"),
  Summary("Create article"),
  JsonBody("article", "Article data", Swagger.valueOf[CreateArticleRequest]),
  Response(201, "Created", Some(Swagger.valueOf[ArticleResponse]))
)
class ApiArticleCreate extends Action {
  def execute(): Unit = {
    respondJson(Map("id" -> 1, "title" -> "New Article", "createdAt" -> System.currentTimeMillis()))
  }
}

// Array response type
@GET("api/articles")
@Swagger(
  Tags("Articles"),
  Summary("List articles"),
  OptIntQuery("page", "Page number"),
  OptIntQuery("limit", "Items per page"),
  Response(200, "Success", Some(Swagger.arrayOf[ArticleResponse]))
)
class ApiArticleList extends Action {
  def execute(): Unit = {
    respondJson(List(
      Map("id" -> 1, "title" -> "Article 1"),
      Map("id" -> 2, "title" -> "Article 2")
    ))
  }
}

```

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

### Define Routes with Annotations in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Illustrates how to define HTTP routes using annotations in Xitrum. Covers GET, POST, PUT, DELETE, and WebSocket routes, including parameter extraction and conditional routing with @First.

```Scala
import xitrum.Action
import xitrum.annotation.{GET, POST, PUT, DELETE, First, Last}

@GET("articles")
@GET("articles/:id<[0-9]+>")
class ArticleIndex extends Action {
  def execute(): Unit = {
    val idOpt = paramo[Int]("id")
    idOpt match {
      case Some(id) => respondJson(Map("id" -> id, "title" -> "Article Title"))
      case None     => respondJson(List(Map("id" -> 1), Map("id" -> 2)))
    }
  }
}

@POST("articles")
class ArticleCreate extends Action {
  def execute(): Unit = {
    val title = param[String]("title")
    val body = param[String]("body")
    respondJson(Map("status" -> "created", "title" -> title))
  }
}

@PUT("articles/:id")
class ArticleUpdate extends Action {
  def execute(): Unit = {
    val id = param[Int]("id")
    respondJson(Map("status" -> "updated", "id" -> id))
  }
}

@DELETE("articles/:id")
class ArticleDelete extends Action {
  def execute(): Unit = {
    val id = param[Int]("id")
    respondJson(Map("status" -> "deleted", "id" -> id))
  }
}

// Use @First to match before other routes
@First
@GET("admin/:*")
class AdminIndex extends Action {
  def execute(): Unit = {
    respondText("Admin area")
  }
}
```

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

### Xitrum Radio Button Validation Example

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Illustrates how to apply validation to radio button groups in Xitrum. The example shows the SecureBase64.encrypt function being used within the validation context for radio inputs, ensuring that only one option can be selected and validated.

```Scala
<input type="radio" name={validate("light")} value="red" />
<input type="radio" name={validate("light")} value="yellow" />
<input type="radio" name={validate("light")} value="green" />
```

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

### Implement WebSocket Communication in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Shows how to create WebSocket actions using the WebSocketAction trait for bidirectional communication. Includes examples of handling text, binary data, and JSON payloads.

```scala
import xitrum.{WebSocketAction, WebSocketText, WebSocketBinary}
import xitrum.annotation.WEBSOCKET

@WEBSOCKET("ws/chat")
class ChatWebSocket extends WebSocketAction {
  def execute(): Unit = {
    respondWebSocketText("Welcome to the chat!")
    context.become {
      case WebSocketText(text) => respondWebSocketText(s"You said: $text")
      case WebSocketBinary(bytes) => respondWebSocketBinary(bytes)
    }
  }
}

@WEBSOCKET("ws/json")
class JsonWebSocket extends WebSocketAction {
  def execute(): Unit = {
    respondWebSocketJson(Map("type" -> "connected"))
    context.become {
      case WebSocketText(text) => respondWebSocketJson(Map("echo" -> text))
    }
  }
}
```

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

### GET /articles

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Retrieves a list of articles or a specific article by ID.

```APIDOC
## GET /articles

### Description
Retrieves a list of all articles or details for a specific article if an ID is provided.

### Method
GET

### Endpoint
/articles/:id

### Parameters
#### Path Parameters
- **id** (Int) - Optional - The unique identifier of the article.

### Request Example
GET /articles/1

### Response
#### Success Response (200)
- **id** (Int) - The article ID
- **title** (String) - The title of the article

#### Response Example
{
  "id": 1,
  "title": "Article Title"
}
```

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

### Accessing Request Parameters in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates type-safe access to request parameters from query strings, form data, path segments, and file uploads. Supports automatic type conversion and handling of optional or multiple values. Includes examples for integer, string, boolean, and file types.

```Scala
import xitrum.Action
import xitrum.annotation.{GET, POST}
import io.netty.handler.codec.http.multipart.FileUpload

@GET("users/:id")
class UserShow extends Action {
  def execute(): Unit = {
    // Required parameter (throws MissingParam if not present)
    val id = param[Int]("id")

    // Optional parameter
    val nameOpt = paramo[String]("name")

    // Parameter with default type (String)
    val query = param("q")

    // Multiple values for same parameter
    val tags = params[String]("tags")

    // Type conversions: Int, Long, Float, Double, Boolean, Char, Byte, Short
    val page = paramo[Int]("page").getOrElse(1)
    val limit = paramo[Int]("limit").getOrElse(10)
    val active = paramo[Boolean]("active").getOrElse(true)

    respondJson(Map(
      "id" -> id,
      "name" -> nameOpt,
      "page" -> page,
      "limit" -> limit
    ))
  }
}

@POST("upload")
class FileUploadAction extends Action {
  def execute(): Unit = {
    // File upload access
    val file = param[FileUpload]("file")
    val filename = file.getFilename
    val contentType = file.getContentType

    // Save uploaded file
    file.renameTo(new java.io.File(s"/uploads/$filename"))

    respondJson(Map("uploaded" -> filename))
  }
}
```

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

### GET /users/:id

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Retrieves user information by ID using type-safe parameter extraction.

```APIDOC
## GET /users/:id

### Description
Retrieves user details based on the provided ID. Demonstrates the use of required and optional parameters with automatic type conversion.

### Method
GET

### Endpoint
/users/:id

### Parameters
#### Path Parameters
- **id** (Int) - Required - The unique identifier of the user.

#### Query Parameters
- **name** (String) - Optional - Filter by user name.
- **page** (Int) - Optional - Pagination page number.
- **limit** (Int) - Optional - Number of items per page.

### Response
#### Success Response (200)
- **id** (Int) - User ID
- **name** (String) - User name
- **page** (Int) - Current page
- **limit** (Int) - Items limit

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "page": 1,
  "limit": 10
}
```

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

### GET /api/users/:id

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Retrieves a single user record by their unique identifier.

```APIDOC
## GET /api/users/:id

### Description
Returns a single user object based on the provided ID.

### Method
GET

### Endpoint
/api/users/:id

### Parameters
#### Path Parameters
- **id** (String) - Required - The unique identifier of the user.

#### Query Parameters
- **fields** (String) - Optional - Comma-separated list of fields to return.

### Response
#### Success Response (200)
- **id** (String) - The user ID
- **name** (String) - The user name

#### Response Example
{
  "id": "1",
  "name": "John Doe"
}
```

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

### Define Custom Error Pages (Scala)

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

This snippet shows how to define custom 404 and 500 error pages using Scala annotations in Xitrum. It includes examples of creating dedicated Action classes for error pages and programmatically triggering these error responses. Dependencies include xitrum.Action and xitrum.annotation.Error404/Error500.

```scala
import xitrum.Action
import xitrum.annotation.{Error404, Error500}

@Error404
class NotFoundPage extends Action {
  def execute(): Unit = {
    respondHtml(
      """
      <html>
        <head><title>404 Not Found</title></head>
        <body>
          <h1>Page Not Found</h1>
          <p>The requested page could not be found.</p>
          <a href="/">Go Home</a>
        </body>
      </html>
      """
    )
  }
}

@Error500
class InternalErrorPage extends Action {
  def execute(): Unit = {
    respondHtml(
      """
      <html>
        <head><title>500 Internal Error</title></head>
        <body>
          <h1>Something went wrong</h1>
          <p>We're working on fixing this.</p>
        </body>
      </html>
      """
    )
  }
}

// Programmatically respond with error pages
@GET("trigger/error")
class ErrorTrigger extends Action {
  def execute(): Unit = {
    val triggerNotFound = paramo[Boolean]("notFound").getOrElse(false)

    if (triggerNotFound) {
      respond404Page()
    } else {
      respond500Page()
    }
  }
}

```

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

### Controller and Action Comparison (Scala)

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Demonstrates how to compare the current controller and action within the Xitrum framework. This is useful for conditional logic based on the active controller or action, aiding in request routing or behavior customization.

```scala
if (currentController == MyController) ...
if (currentAction == MyController.index) ...
```

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

### Configure Sonatype credentials

Source: https://github.com/xitrum-framework/xitrum/blob/master/dev/README.rst

Sets up the required credentials for publishing artifacts to the Sonatype Nexus repository.

```scala
credentials += Credentials("Sonatype Nexus Repository Manager",
                           "oss.sonatype.org",
                           "<your username>",
                           "<your password>")
```

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

### Generate URLs and Redirects in Xitrum (Scala)

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates type-safe URL generation for actions, absolute URLs, public files, WebJars, and SockJS. Also shows how to perform redirects to other actions or URLs, and internal forwards.

```scala
import xitrum.Action
import xitrum.annotation.{GET, POST}
import io.netty.handler.codec.http.HttpResponseStatus

@GET("articles/:id")
class ArticleShow extends Action {
  def execute(): Unit = {
    val id = param[Int]("id")
    respondJson(Map("id" -> id))
  }
}

@GET("url/examples")
class UrlExamples extends Action {
  def execute(): Unit = {
    // Generate URL for another action
    val articleUrl = url[ArticleShow]("id" -> 42)
    // Result: "/articles/42"

    // Absolute URL
    val absArticleUrl = absUrl[ArticleShow]("id" -> 42)
    // Result: "http://example.com/articles/42"

    // Current action URL
    val selfUrl = url

    // Public file URL (with cache busting)
    val jsUrl = publicUrl("js/app.js")

    // WebJars URL
    val jqueryUrl = webJarsUrl("jquery/3.4.1/dist/jquery.min.js")

    // SockJS URL
    val sockJsUrl = sockJsUrl[SockJsChat]

    respondJson(Map(
      "articleUrl" -> articleUrl,
      "absArticleUrl" -> absArticleUrl,
      "publicUrl" -> jsUrl
    ))
  }
}

@POST("articles")
class ArticleCreate extends Action {
  def execute(): Unit = {
    val id = 123  // Created article ID

    // Redirect to another action
    redirectTo[ArticleShow]("id" -> id)

    // Or redirect with status
    // redirectTo[ArticleShow]("id" -> id, HttpResponseStatus.MOVED_PERMANENTLY)

    // Or redirect to URL string
    // redirectTo("https://example.com/articles/123")

    // Or redirect back to self with params
    // redirectToThis("status" -> "created")

    // Or forward (internal, keeps same request)
    // forwardTo[ArticleShow]()
  }
}

```

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

### URL Generation and Redirects

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates how to generate type-safe URLs for actions, absolute URLs, public assets, WebJars, and SockJS, as well as how to perform redirects and forwards.

```APIDOC
## GET /articles/:id

### Description
Retrieves a specific article by its ID.

### Method
GET

### Endpoint
/articles/:id

### Parameters
#### Path Parameters
- **id** (Int) - Required - The unique identifier of the article.

### Response
#### Success Response (200)
- **id** (Int) - The ID of the article.

### Request Example
```json
{
  "example": "No request body for GET"
}
```

### Response Example
```json
{
  "id": 42
}
```

## GET /url/examples

### Description
Provides examples of URL generation, including action URLs, absolute URLs, public asset URLs, WebJars URLs, and SockJS URLs.

### Method
GET

### Endpoint
/url/examples

### Response
#### Success Response (200)
- **articleUrl** (String) - The generated URL for the ArticleShow action.
- **absArticleUrl** (String) - The generated absolute URL for the ArticleShow action.
- **publicUrl** (String) - The generated URL for a public asset with cache busting.

### Request Example
```json
{
  "example": "No request body for GET"
}
```

### Response Example
```json
{
  "articleUrl": "/articles/42",
  "absArticleUrl": "http://example.com/articles/42",
  "publicUrl": "/js/app.js?v=12345"
}
```

## POST /articles

### Description
Creates a new article and then redirects the user to the newly created article's page or another specified URL.

### Method
POST

### Endpoint
/articles

### Parameters
#### Request Body
- **(Implicitly handled by Action parameters)**

### Response
#### Success Response (302 Found or other redirect status)
- **(Redirects to another URL)**

### Request Example
```json
{
  "example": "Request body depends on ArticleCreate action implementation, typically article data."
}
```

### Response Example
```json
{
  "example": "Redirects to /articles/123"
}
```
```

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

### Implement Response Caching in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates how to use page and action level cache annotations to improve performance. Also shows how to perform manual cache operations using the Xitrum configuration object.

```scala
import xitrum.Action
import xitrum.annotation.{GET, CachePageMinute, CacheActionSecond}

@GET("cached/page")
@CachePageMinute(10)
class CachedPageAction extends Action {
  def execute(): Unit = {
    log.info("This log appears only on cache miss")
    respondHtml(s"<p>Generated at: ${System.currentTimeMillis()}</p>")
  }
}

@GET("cached/action")
@CacheActionSecond(30)
class CachedAction extends Action {
  def execute(): Unit = {
    respondJson(Map("timestamp" -> System.currentTimeMillis()))
  }
}

@GET("manual/cache")
class ManualCacheAction extends Action {
  def execute(): Unit = {
    import xitrum.Config
    val cache = Config.xitrum.cache
    val key = "mydata"
    cache.get(key) match {
      case Some(data) =>
        respondJson(Map("cached" -> true, "data" -> data))
      case None =>
        val data = Map("computed" -> "value")
        cache.putMinute(key, data, 5)
        respondJson(Map("cached" -> false, "data" -> data))
    }
  }
}
```

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

### Generate and convert dependency graphs

Source: https://github.com/xitrum-framework/xitrum/blob/master/dev/README.rst

Generates a DOT file representing project dependencies using sbt-dependency-graph, then converts it to a PNG image using Graphviz.

```bash
sbt dependencyDot
dot -Tpng dependencies-compile.dot > deps.png
```

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

### Implement Internationalization (i18n) in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Explains how to use GNU gettext for translations, including context-aware translations, pluralization, and formatting. Also demonstrates how to access browser language preferences.

```scala
import xitrum.Action
import xitrum.annotation.GET

@GET("i18n/example")
class I18nAction extends Action {
  def execute(): Unit = {
    autosetLanguage("en", "ja", "vi", "zh-CN")
    val greeting = t("Hello")
    val menuFile = tc("menu", "File")
    val items = tn("You have %d item", "You have %d items", 5)
    respondJson(Map("language" -> language, "greeting" -> greeting))
  }
}

@GET("languages")
class LanguageAction extends Action {
  def execute(): Unit = {
    import scala.collection.JavaConverters._
    val languages = browserLanguages.asScala.map { range =>
      Map("language" -> range.getRange, "weight" -> range.getWeight)
    }
    respondJson(Map("browserLanguages" -> languages))
  }
}
```

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

### POST /articles

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Creates a new article resource.

```APIDOC
## POST /articles

### Description
Creates a new article using the provided title and body content.

### Method
POST

### Endpoint
/articles

### Parameters
#### Request Body
- **title** (String) - Required - The title of the article
- **body** (String) - Required - The content body of the article

### Request Example
{
  "title": "New Article",
  "body": "Content of the article"
}

### Response
#### Success Response (200)
- **status** (String) - Confirmation status
- **title** (String) - The title of the created article

#### Response Example
{
  "status": "created",
  "title": "New Article"
}
```

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

### Create Reusable View Logic with Components (Scala)

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

This Scala snippet demonstrates how to create reusable view fragments using Xitrum's Component system. Components can share the parent action's context, including session and i18n settings. It shows the definition of HeaderComponent and FooterComponent, and their usage within a HomeAction. Dependencies include xitrum.Action and xitrum.Component.

```scala
import xitrum.{Action, Component}
import xitrum.annotation.GET

class HeaderComponent extends Component {
  def render(): String = {
    val username = sessiono[String]("username").getOrElse("Guest")
    s"""
    <header>
      <nav>
        <a href="${url[HomeAction]}">Home</a>
        <span>Welcome, $username</span>
      </nav>
    </header>
    """
  }
}

class FooterComponent extends Component {
  def render(): String = {
    s"""
    <footer>
      <p>${t("Copyright")} ${java.time.Year.now.getValue}</p>
    </footer>
    """
  }
}

@GET("/")
class HomeAction extends Action {
  def execute(): Unit = {
    val header = newComponent[HeaderComponent]()
    val footer = newComponent[FooterComponent]()

    respondHtml(s"""
      <!DOCTYPE html>
      <html>
        <head><title>Home</title></head>
        <body>
          ${header.render()}
          <main>
            <h1>${t("Welcome to our site")}</h1>
          </main>
          ${footer.render()}
        </body>
      </html>
    """)
  }
}

```

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

### Accessing Configuration in Scala Actions

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates how to access runtime configuration settings within a Xitrum Action using the Config object. This allows developers to dynamically retrieve environment-specific values like production mode or base URLs.

```scala
import xitrum.Config

@GET("config/info")
class ConfigInfo extends Action {
  def execute(): Unit = {
    respondJson(Map(
      "productionMode" -> Config.productionMode,
      "baseUrl" -> Config.baseUrl,
      "charset" -> Config.xitrum.request.charset.name()
    ))
  }
}
```

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

### Dependency Management and Build Options

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This covers changes related to build configurations and dependency management, such as adding `javacOptions` for Java version compatibility and moving parts of the framework to separate projects.

```Scala
// Add javacOptions -source 1.6 to avoid problem when Xitrum is built with
// Java 7 but the projects that use Xitrum are run with Java 6
// Move Scalate template engine out to a separate project
// Move xitrum-sbt-plugin out to a separate project
```

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

### Publish Xitrum locally

Source: https://github.com/xitrum-framework/xitrum/blob/master/dev/README.rst

Publishes the current project to the local Ivy repository. Supports publishing for the default scalaVersion or all cross-compiled versions.

```bash
sbt publishLocal
sbt "+ publishLocal"
```

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

### Input Validation with Xitrum Validators (Scala)

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Illustrates how to use Xitrum's built-in validators for common scenarios like checking for required fields, email format, numeric ranges, string lengths, and URL formats. Shows both exception-throwing and check-and-message approaches.

```scala
import xitrum.Action
import xitrum.annotation.POST
import xitrum.validator._

@POST("users")
class UserCreate extends Action {
  def execute(): Unit = {
    val username = param[String]("username")
    val email = param[String]("email")
    val age = param[Int]("age")
    val password = param[String]("password")

    // Validate required (non-empty)
    Required.exception("Username", username)

    // Validate email format
    Email.exception("Email", email)

    // Validate numeric range
    Range(18, 120).exception("Age", age)

    // Validate string length
    MinLength(8).exception("Password", password)
    MaxLength(100).exception("Password", password)
    RangeLength(8, 100).exception("Password", password)

    // Validate URL format
    xitrum.validator.Url.exception("Website", param[String]("website"))

    // Manual validation with check
    if (!Required.check(username)) {
      response.setStatus(io.netty.handler.codec.http.HttpResponseStatus.BAD_REQUEST)
      respondJson(Map("error" -> "Username is required"))
      return
    }

    // Get validation message without throwing
    val minValidator = Min(0)
    minValidator.message("Balance", -100) match {
      case Some(error) => respondJson(Map("error" -> error))
      case None => respondJson(Map("status" -> "valid"))
    }

    respondJson(Map("status" -> "created", "username" -> username))
  }
}

```

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

### Configuration File Format Change (Scala)

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Illustrates the migration of Xitrum's configuration file from JSON format to HOCON (Typesafe Config) format. This change allows for more flexible and powerful configuration options.

```scala
Change config/xitrum.json to config/xitrum.conf
```

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

### Publish signed artifacts to Sonatype

Source: https://github.com/xitrum-framework/xitrum/blob/master/dev/README.rst

Executes the signed publication process to Sonatype, requiring GPG for artifact signing.

```bash
brew install gnupg
sbt "+ publishSigned"
```

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

### Xitrum Configuration File Structure

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

The xitrum.conf file defines server bindings, HTTPS settings, session management, and performance tuning parameters. It uses a HOCON-like syntax to configure the framework's behavior.

```hocon
xitrum {
  interface = "0.0.0.0"
  port {
    http = 8000
    https = 4430
  }
  session {
    cookieName = "_session"
    secureKey = "your-secret-key"
  }
  cache = "xitrum.local.LruCache"
}
```

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

### Xitrum Configuration Structure (HOCON)

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

This snippet illustrates the configuration structure for Xitrum, which uses HOCON files. It specifies that the main configuration is located in `config/xitrum.conf` and application-specific settings are in `config/application.conf`. This format allows for hierarchical and flexible configuration management.

```hocon
# Main configuration is in config/xitrum.conf
# Application-specific settings in config/application.conf

```

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

### SockJS Chat Implementation in Scala

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Demonstrates a basic SockJS chat application using Xitrum. It handles incoming text messages, echoes them back, and manages session data. Dependencies include xitrum and akka-actor.

```scala
import xitrum.{SockJsAction, SockJsText}
import xitrum.annotation.{SOCKJS, SockJsCookieNeeded, SockJsNoWebSocket}
import akka.actor.ActorRef
import scala.collection.mutable

@SOCKJS("sockjs/chat")
class SockJsChat extends SockJsAction {
  def execute(): Unit = {
    log.info(s"SockJS session started from ${remoteIp}")

    // Access session data from the HTTP request that initiated SockJS
    val usernameOpt = sessiono[String]("username")

    respondSockJsText(s"Welcome ${usernameOpt.getOrElse("Guest")}!")

    context.become {
      case SockJsText(text) =>
        log.info(s"Received: $text")
        respondSockJsText(s"Echo: $text")
    }
  }

  override def postStop(): Unit = {
    log.info("SockJS session ended")
    super.postStop()
  }
}

// With cookie requirement for sticky sessions behind load balancer
@SOCKJS("sockjs/sticky")
@SockJsCookieNeeded
class StickySockJs extends SockJsAction {
  def execute(): Unit = {
    respondSockJsText("Cookie-based session")
  }
}

// Disable WebSocket transport (use polling only)
@SOCKJS("sockjs/polling")
@SockJsNoWebSocket
class PollingOnlySockJs extends SockJsAction {
  def execute(): Unit = {
    respondSockJsText("Polling transport only")
  }
}

// Send JSON via SockJS
@SOCKJS("sockjs/json")
class JsonSockJs extends SockJsAction {
  def execute(): Unit = {
    respondSockJsJson(Map("event" -> "connected"))

    context.become {
      case SockJsText(text) =>
        respondSockJsJson(Map("echo" -> text))
    }
  }
}
```

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

### Compare files using opendiff

Source: https://github.com/xitrum-framework/xitrum/blob/master/dev/README.rst

Uses the opendiff GUI tool on macOS to compare two files, useful for checking mime.types or configuration changes.

```bash
opendiff file1 file2
```

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

### POST /upload

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Handles file uploads and saves them to the server filesystem.

```APIDOC
## POST /upload

### Description
Processes a multipart file upload and saves the file to a designated directory.

### Method
POST

### Endpoint
/upload

### Request Body
- **file** (FileUpload) - Required - The file object to be uploaded.

### Response
#### Success Response (200)
- **uploaded** (String) - The name of the saved file.

#### Response Example
{
  "uploaded": "image.png"
}
```

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

### Session Management in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Covers session management features in Xitrum, including storing and retrieving session data with type safety, using cookies for storage, and clearing sessions. Demonstrates login, dashboard, and logout actions, as well as cookie manipulation.

```Scala
import xitrum.Action
import xitrum.annotation.{GET, POST}

@GET("login")
class LoginPage extends Action {
  def execute(): Unit = {
    respondHtml("<form method='post'><input name='username'/><button>Login</button></form>")
  }
}

@POST("login")
class LoginAction extends Action {
  def execute(): Unit = {
    val username = param[String]("username")

    // Store in session (mutable map)
    session("userId") = 123
    session("username") = username
    session("roles") = List("admin", "user")

    redirectTo[DashboardAction]()
  }
}

@GET("dashboard")
class DashboardAction extends Action {
  def execute(): Unit = {
    // Retrieve from session with type safety
    val userIdOpt = sessiono[Int]("userId")
    val usernameOpt = sessiono[String]("username")

    userIdOpt match {
      case Some(userId) =>
        respondJson(Map("userId" -> userId, "username" -> usernameOpt))
      case None =>
        redirectTo[LoginPage]()
    }
  }
}

@GET("logout")
class LogoutAction extends Action {
  def execute(): Unit = {
    // Clear session
    session.clear()
    redirectTo[LoginPage]()
  }
}

// Working with cookies
@GET("cookies")
class CookieAction extends Action {
  def execute(): Unit = {
    // Read request cookies
    val tokenOpt = requestCookies.get("token")

    // Set response cookie
    import io.netty.handler.codec.http.cookie.DefaultCookie
    val cookie = new DefaultCookie("preference", "dark-mode")
    cookie.setMaxAge(86400 * 30)  // 30 days
    cookie.setHttpOnly(true)
    responseCookies.append(cookie)

    respondText("Cookie set")
  }
}
```

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

### Configuration and Utility Functionality Updates

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This snippet includes updates related to application configuration, such as enabling apps to use no template engine, and utility function changes like renaming base64 encoding methods.

```Scala
// Apps can be configured to use no template engine
// Rename xitrum.util.Base64 to UrlSafeBase64, SecureBase64 to SecureUrlSafeBase64
```

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

### Define Route with Regex Requirements

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Shows how to restrict route parameters using regular expressions to ensure input validation at the routing level.

```scala
def show = GET("/articles/:id<[0-9]+>") { ... }
```

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

### Update Logging Libraries

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This covers updates to logging libraries like SLF4J and Logback to newer versions, ensuring compatibility and potentially incorporating bug fixes or performance improvements from the logging providers.

```Scala
// Update SLF4J from 1.7.2 to 1.7.3, Logback from 1.0.9 to 1.0.10
// You should update Logback in your project from 1.0.9 to 1.0.10
// Update slf4j-api to 1.7.5
```

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

### Performance and Dependency Reduction

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This section highlights efforts to improve performance and reduce project dependencies, such as replacing Javassist with ASM and speeding up CoffeeScript compilation.

```Scala
// Replace Javassist with ASM to reduce the number of dependencies
// Speed up CoffeeScript compiling by using
// https://github.com/xitrum-framework/RhinoCoffeeScript
```

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

### Tag new release in Git

Source: https://github.com/xitrum-framework/xitrum/blob/master/dev/README.rst

Commands to list existing tags and push a new version tag to the remote repository.

```bash
git tag --list
git tag <new version number>
git push origin <new version number>
```

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

### URL Handling and Path Management

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This focuses on improvements to URL handling, including renaming URL generation methods and ignoring trailing slashes in URLs for consistent routing.

```Scala
// Rename urlForPublic to publicUrl, urlForResource to resourceUrl
// Ignore trailing slash in URL: treat "articles" and "articles/" the same
```

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

### Logging and Serialization Updates

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This snippet addresses changes in logging mechanisms, switching from SLF4J to Akka log, and serialization issues, particularly with SockJsClassAndOptions in production mode.

```Scala
// Use Akka log instead of using SLF4J directly
// Can't run in production mode because SockJsClassAndOptions
// in routes can't be serialized
```

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

### POST /api/users

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Creates a new user account using form data.

```APIDOC
## POST /api/users

### Description
Creates a new user in the system.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **username** (String) - Required - Username for the new account.
- **email** (String) - Required - Email address.
- **bio** (String) - Optional - User biography.

### Response
#### Success Response (201)
- **id** (Integer) - The ID of the created user
- **username** (String) - The username

#### Response Example
{
  "id": 123,
  "username": "johndoe"
}
```

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

### Scalate Template Rendering from String (Scala)

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Introduces new methods for rendering Scalate templates directly from string content, rather than solely from files. This provides greater flexibility in dynamic template generation.

```scala
Add methods to render Scalate templates directly from strings (non-file)
```

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

### Error Handling and Bug Fixes

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This snippet addresses specific bug fixes, such as resolving NullPointerExceptions with basic authentication and ensuring proper handling of abstract controller instantiation during route collection.

```Scala
// Basic authentication causes NullPointerException
```

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

### Asynchronous Operations with FutureAction and ActorAction in Scala

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Illustrates how to perform asynchronous and long-running operations using Xitrum's FutureAction and ActorAction. FutureAction is suitable for CPU-bound tasks, while ActorAction leverages Akka actors for more complex scenarios, including external actor communication. Dependencies include xitrum and akka-actor.

```scala
import xitrum.{Action, FutureAction, ActorAction}
import xitrum.annotation.GET
import scala.concurrent.Future

// FutureAction - for async operations
@GET("async/future")
class AsyncFutureAction extends FutureAction {
  def execute(): Unit = {
    // This runs in Akka dispatcher, not Netty IO thread
    Future {
      Thread.sleep(1000)  // Simulate slow operation
      "Result from future"
    }.foreach {
      result =>
        respondJson(Map("result" -> result))
    }
  }
}

// ActorAction - full Akka actor capabilities
@GET("async/actor")
class AsyncActorAction extends ActorAction {
  def execute(): Unit = {
    // Schedule a message to self
    import scala.concurrent.duration._
    context.system.scheduler.scheduleOnce(1.second, self, "delayed")
  }

  override def receive: Receive = {
    case (env, skipCsrfCheck: Boolean) =>
      super.receive.apply((env, skipCsrfCheck))

    case "delayed" =>
      respondJson(Map("message" -> "Delayed response from actor"))
  }
}

// ActorAction with external actor communication
@GET("async/external")
class ExternalActorAction extends ActorAction {
  def execute(): Unit = {
    import akka.pattern.ask
    import akka.util.Timeout
    import scala.concurrent.duration._

    implicit val timeout: Timeout = Timeout(5.seconds)

    // Assuming some external actor exists
    val externalActor = context.system.actorSelection("/user/dataService")

    (externalActor ? "getData").mapTo[String].foreach {
      data =>
        respondJson(Map("data" -> data))
    }
  }
}
```

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

### Respond with WebSocket Data in Xitrum

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Handles responses for WebSocket connections, sending binary data through the established WebSocket channel. Requires a ChannelBuffer.

```Scala
respondWebSocket(channelBuffer: ChannelBuffer)
```

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

### Respond to Requests in Xitrum

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Shows various methods for responding to client requests within Xitrum Actions. Supports plain text, HTML, JSON, JSONP, XML, binary data, files, and resources, along with custom status codes and chunked transfer encoding.

```Scala
import xitrum.Action
import xitrum.annotation.GET
import io.netty.handler.codec.http.HttpResponseStatus

@GET("examples/responses")
class ResponseExamples extends Action {
  def execute(): Unit = {
    // Plain text response
    respondText("Hello World")

    // Or HTML response
    respondHtml("<h1>Hello World</h1>")

    // Or JSON from Scala object
    respondJson(Map("message" -> "Hello", "count" -> 42))

    // Or JSON text directly
    respondJsonText("{\"raw\": \"json\"}")

    // Or JSONP response
    respondJsonP(Map("data" -> "value"), "callbackFunction")

    // Or XML response
    respondXml(<root><item>Value</item></root>)

    // Or binary data
    respondBinary(Array[Byte](1, 2, 3, 4))

    // Or file from filesystem
    respondFile("/path/to/file.pdf")

    // Or resource from classpath
    respondResource("public/image.png")

    // Set custom status code
    response.setStatus(HttpResponseStatus.CREATED)
    respondJson(Map("id" -> 123))
  }
}

// Chunked transfer encoding
@GET("stream")
class StreamAction extends Action {
  def execute(): Unit = {
    setChunked()
    respondText("First chunk\n")
    respondText("Second chunk\n")
    respondText("Third chunk\n")
    respondLastChunk()
  }
}

// Server-Sent Events
@GET("events")
class EventSourceAction extends Action {
  def execute(): Unit = {
    respondEventSource("Initial data", "connect")
    // Later send more events...
    respondEventSource("Update 1", "message")
    respondEventSource("Update 2", "message")
  }
}
```

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

### Respond with JSONP Text in Xitrum

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Similar to respondJsonP, but accepts a pre-formatted JSON string and a callback function name for JSONP responses.

```Scala
respondJsonPText("[1, 2, 3]", "myFunction")
```

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

### Refactor Controller Actions and SockJS Handling

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This section details refactoring efforts to break down controller actions into separate classes (Action or ActionActor) and improvements to SockJS handling, including session and request header access.

```Scala
// Break actions in controller out to separate classes, each is an Action or an ActionActor; your action can be an actor
// Rewrite part of SockJS using ActionActor
// Add connection abort handling for SockJS
// Support "/" in SockJS path prefix
// Support WebSocket binary frame
// SockJS handler can now access session, request headers etc.
// def onOpen(session: immutable Map[String, Any]) -> def onOpen(controller: Controller)
```

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

### Respond with JSONP in Xitrum

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This method handles JSONP (JSON with Padding) responses, which allows for cross-domain requests. It takes a list of data and a callback function name.

```Scala
respondJsonP(List(1, 2, 3), "myFunction")
```

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

### Respond with Binary Data in Xitrum

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This method is used to send binary data as a response. It accepts a ChannelBuffer, which is a Netty-specific buffer type.

```Scala
respondBinary(channelBuffer: ChannelBuffer)
```

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

### Add New Functionality: redirectToThis and forwardTo

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Introduces new methods for controlling request flow: `redirectToThis` for redirecting to the current action and `forwardTo` for forwarding requests.

```Scala
// Add redirectToThis to redirect to the current action
// Add forwardTo
```

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

### Render Xitrum CSS in Xitrum

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Includes the default Xitrum CSS file in your HTML. This is a shortcut for linking the framework's stylesheets.

```Scala
!= xitrumCSS
```

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

### Update Dependencies: Twitter Chill, jQuery, Netty, etc.

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This snippet covers various updates to external libraries and dependencies used within the Xitrum framework. These updates often include performance improvements, bug fixes, and new features from the upstream libraries.

```Scala
// Update Twitter Chill to 0.2.3
// Update jQuery to 1.10.0
// Update Twitter Chill to 0.2.2
// Update Twitter Chill to 0.2.1
// Update Hazelcast to 2.5.1
// Update JSON4S to 3.2.4
// Update Netty to 3.6.4
// Update JSON4S to 3.2.3
// Update Netty to 3.6.5
// Update Netty to 3.6.3
// Update Netty to 3.6.2
```

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

### Update SockJS Handler Interface (Scala)

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This snippet shows the change in the SockJS handler interface from a no-argument `onOpen` method to one that accepts a session map. This change likely enhances the information available during a SockJS connection's opening.

```scala
def onOpen() -> def onOpen(session: immutable Map[String, Any])
```

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

### Respond with HTML in Xitrum

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This method is used to send an HTML response to the client. It takes an HTML string as input.

```Scala
respondHtml("<html>...</html>")
```

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

### Fragment Rendering (Scala)

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

Adds a `renderFragment` method to the controller, allowing for the rendering of specific fragments of the current controller's view. This facilitates more modular and reusable view components.

```scala
Add renderFragment(fragment: String) which renders a fragment of the current controller
```

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

### Security and Utility Enhancements

Source: https://github.com/xitrum-framework/xitrum/blob/master/CHANGELOG.rst

This covers improvements to security-related utilities, such as enhancing the `Secure#unseal` method.

```Scala
// Improve Secure#unseal
```

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

### POST /api/articles

Source: https://context7.com/xitrum-framework/xitrum/llms.txt

Creates a new article using a JSON request body.

```APIDOC
## POST /api/articles

### Description
Creates a new article entry.

### Method
POST

### Endpoint
/api/articles

### Parameters
#### Request Body
- **article** (Object) - Required - The article data containing title, body, and tags.

### Response
#### Success Response (201)
- **id** (Integer) - The ID of the created article
- **title** (String) - The title of the article
- **createdAt** (Long) - Timestamp of creation

#### Response Example
{
  "id": 1,
  "title": "New Article",
  "createdAt": 1625000000000
}
```
Tokens:
Raw