Routing

HTTP Methods

Use these helpers to define routes for different HTTP methods:

Basic Routes

# Root page
get("/", "home#index")
# Static pages
get("/about", "home#about")get("/contact", "home#contact")
# Form submissions
post("/contact", "home#submit_contact");

Route Parameters

Use :param_name to capture dynamic segments:

# Capture user ID
get("/users/:id", "users#show")
# Multiple parameters
get("/posts/:post_id/comments/:comment_id", "comments#show")
# Optional parameters
get("/users/:id?", "users#show");

Access parameters in your controller:

def show(req: Any)
user_id = req["params"]["id"]
  post_id = req["params"]["post_id"]

  {
    "status": 200,
    "body": "User ID: " + user_id
  }
end

Splat Routes

Use *param_name to capture the remaining path segments greedously:

# Capture remaining path
get("/files/*filepath", "files#serve")get("/downloads/*filename", "downloads#handle")
# Combine with parameters
get("/users/:id/*action", "users#action")get("/api/*version/users/*id", "api#user")
# Root splat
get("/*path", "catchall#handle");

Captured splat values include a leading slash:

def serve(req: Any)
filepath = req["params"]["filepath"]

  # /files/docs/report.pdf -> filepath = "/docs/report.pdf"
  # /files/images/photo.jpg -> filepath = "/images/photo.jpg"

  {
    "status": 200,
    "body": "Serving: " + filepath
  }
end

Wildcard Action Routes

Use controller#* to dynamically resolve actions from the URL path:

# Dynamic docs routes - /docs/routing → docs#routing
get("/docs/*", "docs#*")
# API routes with version - /api/v1/users → api#users
get("/api/*version/*action", "api#*")
# Files serving - /files/docs/readme → files#docs/readme
get("/files/*filepath", "files#serve");

The action name is resolved from captured splat parameters in this priority order:

1. splat parameter
2. path, filepath, filename, action, or resource
3. First non-nested parameter

class DocsController < Controller
  static
    this.layout = "docs"
  end

  def routing(req: Any)
path = req["params"]["path"];  # "/routing"
    render("docs/routing", {"active_page": "routing"})
  end

  def installation(req: Any)
render("docs/installation", {"active_page": "installation"})
  end
end

Query Parameters

Query strings are automatically parsed and available in req["query"]:

# URL: /search?q=solilang&page=1

def search(req: Any)
query = req["query"]["q"];      # "solilang"
  page = req["query"]["page"];    # "1"

  {
    "status": 200,
    "body": "Searching for: " + query
  }
end

RESTful Resources

Generate standard CRUD routes automatically with resources():

resources("users")

Named Routes

Every route registered via resources() automatically gets a pair of Rails-style helpers — <name>_path for the relative path and <name>_url for the absolute URL — defined as global functions in every worker. Use them anywhere you'd otherwise concatenate a URL by hand:

# In a controller
return redirect(post_path(post))

# In an ERB view
<a href="<%= edit_post_path(post) %>">Edit</a>

For resources("posts") you get:

Each one has a matching *_url variant (posts_url(), post_url(post), …) that returns the absolute form (https://example.com/posts/42).

How the argument is interpreted

post_path accepts the id in three shapes:

post_path(post)         # reads post.id off the model instance
post_path(42)           # raw int / string
post_path({"id": 42})   # explicit hash

For multi-param routes, pass either a hash or positional primitives in declaration order:

# pattern: /posts/:post_id/comments/:id
post_comment_path({"post_id": 5, "id": 9})
post_comment_path(5, 9)

Calling a helper without the params it needs raises a clear runtime error (post_path: missing param :id).

*_url and host resolution

Inside a request handler <name>_url reads the scheme and host from the current request (honouring X-Forwarded-Proto / X-Forwarded-Host for apps behind a proxy). Outside a request — e.g. from a background job, a CLI script, or a test — set SOLI_DEFAULT_URL_HOST (and optionally SOLI_DEFAULT_URL_SCHEME, defaults to http) and the helpers will use that. With neither in scope the helper raises <name>_url: cannot resolve host (no active request and SOLI_DEFAULT_URL_HOST not set).

Naming a custom route with name:

For one-off routes registered via get/post/put/delete/patch, attach a name with the name: keyword argument and the matching *_path / *_url helpers are generated for it too:

get("/about", "pages#about", name: "about")
# → about_path()  →  "/about"
# → about_url()   →  "https://example.com/about"

(name: rather than Rails' as: because as is a reserved keyword in Soli.)

Plural-to-singular limitations

resources() derives the member-route helper (<singular>_path) and the nested-resource param (:<singular>_id) from the resource name by a small built-in inflector. It handles three cases:

• Trailing s — posts → post, users → user.
• ies → y after a consonant — categories → category, parties → party, companies → company.
• A short irregulars table — people → person, men → man, women → woman, children → child, mice → mouse, geese → goose, feet → foot, teeth → tooth.

Anything else falls through unchanged, which can produce a confusing helper name or a collision with the collection helper. The two failure modes worth knowing:

• Words whose plural doesn't end in s and aren't in the irregulars table (e.g. data, sheep, series, news) leave the singular equal to the plural, so data_path() would mean both the collection and the member route. The member registration overwrites the collection in the route table — usually not what you want. Pick a different resource name (e.g. entries).
• Words where ies → y produces nonsense are caught by the consonant guard (pies → pie, not py), but exotic forms still won't round-trip. When in doubt, register the routes manually with get(..., name: "...").

Duplicate names

Registering two routes with the same name: is allowed; the last route to be added wins the helper. Hot reload follows the same rule because the lookup table is rebuilt from the live route list on every reload. There is no compile-time warning today, so audit config/routes.sl if <name>_path ever returns a path you weren't expecting.

Namespaces

Group routes under a common prefix, like /admin:

namespace("admin", ->
  get("/dashboard", "admin#dashboard")
  get("/users", "admin#users")
  post("/users", "admin#create_user"))

Scoped Middleware

Apply middleware only to specific route blocks:

# Only /admin/* routes require authentication
middleware("authenticate", ->
  get("/admin", "admin#index")
  get("/admin/users", "admin#users"))

# Public routes - no auth needed
get("/", "home#index")
get("/about", "home#about")

Auto-routed attachments

Mount the standard show / create / destroy endpoints for a model field declared with uploader(...):

uploads("contacts", "photo")

The shared AttachmentsController ships with the framework — you don't need to add any controller file. It recovers the resource and field segments from the request path, looks up the model class via find_model_class_by_collection, and delegates to the uploader's attach_/detach_ methods.

For image fields, the show endpoint also supports on-the-fly transforms via query params: ?square=200 (avatar shorthand), ?w=200&h=200&fit=cover, ?thumb=100, ?crop=10,20,300,200, ?rot=90&flipx=1, ?blur=2.5&bright=10&contrast=1.2, ?gray=1&invert=1, ?fmt=webp&q=80. See Image transforms via URL in the model docs for the full param list and the matching upload_url(model, field, options) builder.

To customize behavior (extra auth, alternative response shape, different storage), define your own class AttachmentsController < ApplicationController in app/controllers/attachments_controller.sl — user controllers load after the framework prelude so your version wins automatically.

Nested Resources

namespace("api", ->
  resources("users", ->
    resources("posts", ->
      resources("comments")
    )
  )
)
# Creates: /api/users/:user_id/posts/:post_id/comments/:id

Nested Controllers

Controllers nested in subdirectories of app/controllers/ are addressed with a /-separated key:

# app/controllers/admin/merchants_controller.sl → AdminMerchantsController
get("/admin/merchants", "admin/merchants#index")
get("/admin/merchants/:id", "admin/merchants#show")

resources("/admin/merchants", "admin/merchants")

See Controllers → Nested Controller Directories for the full naming rules.

CSRF Protection

# config/routes.sl

# Exact path:
skip_csrf("/webhooks/stripe");
post("/webhooks/stripe", "webhooks#stripe");

# Whole prefix:
skip_csrf("/api/*");
post("/api/users", "api#users_create");
post("/api/orders", "api#orders_create");

Next Steps