Runcobo is a general purpose framework built on Crystal.
Runcobo 3.0 uses request-validation contracts for typed request inputs. It is a
breaking change from 2.x; see the migration notes below. Version 3.0.0 depends
on the tagged jbuilder 1.1.0 and private request-validation 0.1.0 releases.
runcobo [<commands>...] [<arguments>...]
Commands:
routes - Print all routes of the app.
version - Print the current version of the runcobo.
help - Print usage synopsis.
Options:
-h, --help Print usage synopsis.
-v, --version Print the current version of the runcobo.lib/ # Library
src/
main.cr # Entry file
actions/ # Actions Directory
...
assets/ # Assets Directory
views/ # Views Directory
layouts/ # Layouts directory
...
models/ # Models Directory
...
shards.yml # The packages congfiuration file
shards.lock # The lock file for packages congfiuration file
Keep in this architecture to use layouts macro, render macro.
MVC (Model-View-Controller)
- Simple Design must be simple, both in implementation and interface.
- Intuitive Design must be intuitive.
- Consistent Design must be consistent.
Crystal is a language for humans and computers.
Crystal is a type safe, compiled language inspired by the simplicity of Ruby. Type safety means more errors are caught by the compiler during development, so you can be more confident about your code working in production.
See https://crystal-lang.org/install/ to install Crystal.
You can install Runcobo from sources. Crystal >= 1.22.0 and < 2.0.0 is required.
The request-validation dependency is private: configure an authenticated Git
connection with read access to shootingfly/request-validation before installing.
The manifest uses the repository's secure-shell Git address.
git clone https://github.com/runcobo/runcobo.git
cd runcobo
make build
./bin/runcobo --version
# Optional installation into a writable directory:
make install INSTALL_DIR="$HOME/.local/bin"1.Init a Crystal project.
crystal init app demo && cd demo2.Add the dependency to your shard.yml and run shards install.
dependencies:
runcobo:
github: runcobo/runcobo
version: 3.0.03.Write down the following code in src/demo.cr.
require "runcobo"
class AddContract < RequestValidation::Contract
schema do
required :a, Int32
required :b, Int32
end
end
class Api::V1::Add < BaseAction
get "/api/v1/add"
query AddContract
call do
sum = input.a + input.b
render_plain sum.to_s
end
end
Runcobo.start4.Run server.
crystal src/demo.cr5.Send request.
curl "http://0.0.0.0:3000/api/v1/add?a=1&b=2"6.Auto restart server.
# Use nodemon to watch file changed and auto restart server.
sudo npm install -g nodemon
nodemon -e "cr,water,jbuilder,yml" --exec "crystal run" src/demo.crRuncobo declares routes in every Actions. If you access the route, it will run into related Action.
In this way, you can know the routes of current Action quickly.
You can declare RESTful routes as you want or not.
In my personal view, RESTful is too abstact when you were far way from a CRUD system like Backend Management System.
When writing API, I believe urls should be named like functions, not objects or resources.
When writing a Backend Management System, enjoy RESTful.
Runcobo declares routes by following methods: get, post, put, patch, delete, options, head.
An Action can bind to one or more routes.
class Example < BaseAction
get "/books"
get "/books/:id"
post "/books"
put "/books/:id"
patch "/books/:id"
delete "/books/:id"
options "/books/:id"
head "/books/:id"
call do
render_plain "Hello World"
end
endURL Params can be declared in the route like /add/:apple_count/:banana_count. And then you should use url method to declare the type of URL params.
class FruitCountContract < RequestValidation::Contract
schema do
required :apple_count, Int32
required :banana_count, Int32
end
end
class Example < BaseAction
get "/add/:apple_count/:banana_count"
url FruitCountContract
call do
sum = input.apple_count + input.banana_count
render_plain sum.to_s
end
endIf you need a route with custom HTTP method, such as LINK, UNLINK, FIND or PURGE, then you can use route method to declare it.
class Example < BaseAction
route "LINK", "/books/:id"
call do
render_plain "Hello World"
end
endRuncobo use one action one file.
class BeforeExample < BaseAction
before required_login
def required_login
Runcobo::Log.info { "Required Login" }
end
get "/before_example"
call do
render_plain "Hello World!"
end
endclass AfterExample < BaseAction
after log_request
def log_request
Runcobo::Log.info { "#{request.path}" }
end
get "/after_example"
call do
render_plain "Hello World!"
end
endclass BaseAction
before required_login
def required_login
Runcobo::Log.info { "Required Login" }
end
end
class SkipExample < BaseAction
skip required_login
get "/skip_example"
call do
render_plain "Hello World!"
end
endFor a request-level contract, call validate in the action body:
class Authors::Create < BaseAction
post "/authors"
call do
input = validate(CreateAuthorContract)
render_json({name: input.name, bio: input.bio}, status_code: 201)
end
endThis returns the contract's native Output. Unknown fields are stripped by
default; use validate(CreateAuthorContract, strict: true) to reject them.
Failures raise Runcobo::Validation::Failure, unwind the action body, and reach
render_validation_errors. Code after a failed validation and after filters
do not run. Programming errors in rules continue to propagate normally.
Request-level input combines query fields, ordinary body fields and route
fields. Structured body fields replace same-named query fields; route fields
replace either. Ordinary form values append to query values, so repeated scalar
fields remain errors. Query and form requests use native from_params
conversions. Requests with a structured body use from_json for the combined
object: query and route values remain strings in that mode. Use the separate
source contracts below when sources need independent conversion or validation.
An empty structured body is treated as an empty object for this entry.
To check body format even on actions without a contract, opt in after your authentication filter:
abstract class AppAction < BaseAction
before_request authenticate
before_request read_input
endread_input checks format and caches input; validate(Contract) checks fields.
No empty contract is needed. skip read_input skips inherited preparation for
an unconditional endpoint. Read-only GET and HEAD requests ignore the body.
Multipart fields use native parameter conversions; uploaded files are accessed
separately with upload or uploads.
Declare a RequestValidation::Contract and bind it to the action's input source.
Runcobo loads request-validation through the normal entry point. Installing the
framework requires read access to the private shootingfly/request-validation
repository; the pinned dependency is installed transitively.
require "runcobo"
class CreateAuthorContract < RequestValidation::Contract
schema do
required :name, String
optional :bio, String, nullable: true
end
rule :name do |name, errors|
errors.add(:name, :blank) if name.empty?
end
end
class Authors::Create < BaseAction
post "/authors"
json CreateAuthorContract
call do
render_json({name: input.name, bio: input.bio}, status_code: 201)
end
end
Runcobo.starturl, query, form, and json accept contract types. A single contract
provides input; multiple contracts provide url_input, query_input,
form_input, and json_input for the declared sources. These are concrete
contract outputs, with required fields retaining non-nullable types. Sources
are validated separately and their errors are collected together; same-named
fields do not overwrite each other. Results are cached only on the current
action instance, so repeated access does not rerun rules or reread the body.
Contracts support String, Int32, Int64, Float64, Bool, JSON::Any,
scalar arrays and nested contracts. Optional fields may be missing; explicit null requires
nullable: true. Use the generated field_present? accessor to distinguish
missing fields from explicit null when updating records. Required strings can
still be empty; add a constraint or rule when blank strings are invalid.
Query, path and form values use the contract's string conversions. Contract
booleans accept only true and false, and repeated scalar query/form fields
are rejected. Structured bodies retain their native types: strings are not
converted into numbers or booleans. Unknown fields are stripped by default, matching validate;
use query SomeContract, unknown_keys: :reject (or the corresponding source)
to reject them explicitly.
Each source may have only one contract, including inherited declarations. An
action cannot declare both a form and a structured-body contract. Conflicts and
old NamedTuple parameter declarations fail at compile time. Shared filters can
live in a base action without parameter declarations.
Failures return an application/json response with an errors array:
{
"errors": [
{"source": "query", "path": ["id"], "code": "invalid_type", "params": {"expected": "Int64"}}
]
}Errors preserve the contract's paths, stable codes and message parameters,
without including raw input values. Field failures, custom rule failures and
non-object bodies return 422. Malformed structured bodies return 400. Body
contracts require the corresponding media type: application/json (including
application/*+json) or application/x-www-form-urlencoded; unsupported or
missing media types return 415. Media type parameters such as a charset are
accepted. A form contract also accepts ordinary fields from multipart/form-data;
files are kept separately from contract fields. Malformed multipart bodies return 400.
Contract bodies are read lazily and limited to 1,048,576 bytes by default,
including bodies without a content length. Exceeding the limit returns 413.
Override max_request_body_size : Int64 on an action to change this limit.
Reading starts when a body contract, direct validation, read_input, or explicit
middleware buffering needs it; it does not happen in the action constructor.
Both contract styles and read_input share request.runcobo_input: raw bytes,
parsed query/form fields and parsed structured input are cached per request.
Middleware can set request.runcobo_input.max_body_size and call body to enforce
a limit using the same buffer for non-multipart requests. For multipart requests,
middleware only configures the limit; the parser counts bytes while receiving
parts, without caching the entire body string. Declared contract results are
cached per action; explicit validate
calls run their contracts against the cached input on each call. There is no
second parser or additional coercion layer.
The action body and existing before/after filters run only after validation
succeeds. For authentication or other checks that must run before body reading,
use before_request method_name. These filters support inheritance and skip;
render a response and return byebye to halt without parsing or validating.
An early halt or validation failure skips the remaining action filters and body.
Override render_validation_errors(issues : Array(Runcobo::Validation::Issue), *, status_code : Int32) to customize error responses. Rules' programming errors
continue to propagate as exceptions. For contracts with constructor dependencies,
override build_query_contract, build_url_contract, build_form_contract, or
build_json_contract on the action to return the configured contract instance.
Runcobo 3.0 removes the old parameter mode instead of maintaining two parsers:
- Replace
query NamedTuple(...)(andurl,form,json) with a contract class containingschemadeclarations. Unsupported declarations fail with a migration diagnostic at compile time. - Replace the merged
params[:field]access withinput.fieldfor one source, or a source accessor such asurl_input.fieldwhen there are multiple sources. There is no implicit source priority orparams[:__action]; useself.class.namefor the action name. - Use
optionalfor missing fields andnullable: truefor explicit null. Optional output types require nil handling; presence accessors distinguish missing/null. - Both contract entry styles strip unknown fields by default. Explicit rejection uses
strict: truewithvalidate, orunknown_keys: :rejectwith a source declaration. Repeated scalar fields are errors, and boolean strings must betrueorfalse. The primitivefrom_http_paramextensions andparse_paramshelpers are removed. - Send the correct body media type, account for the default body limit and error
response statuses, and move authentication to
before_requestwhen appropriate. - Nested contracts and scalar arrays are supported. Custom conversion types are not.
- Declare field constraints in
schema, for examplerequired :count, Int64, gteq: 2, lteq: 100. Their error codes, paths and parameters pass through the same validation response as custom rules.
Actions explicitly declare head routes and choose their response. Runcobo does
not fall back from HEAD to GET, or globally remove response bodies for HEAD
or status 304. Use render_empty before writing any output:
class Status::Show < BaseAction
get "/status"
head "/status"
call do
if request.method == "HEAD"
render_empty content_type: "application/json"
else
render_json({status: "ok"})
end
end
endrender_empty status_code: 304 also returns an empty conditional response when
chosen by an action. It sets status and optional content type without rendering a
template or clearing previously written data. Set representation headers such as
ETag and Content-Length in the action when needed.
Customize missing routes without an additional middleware class:
Runcobo::RouteNotFoundHandler.new do |context|
context.response.status_code = 404
context.response.content_type = "application/json"
context.response.print(%({"error":"not_found"})) unless context.request.method == "HEAD"
endThe callback owns the complete missing response, including empty bodies. Without a callback, the existing 404 text response is unchanged.
Mount a directory by placing StaticFiles before the action router:
Runcobo.start handlers: [
Runcobo::StaticFiles.new("/assets", directory: "public", cache_control: "public, max-age=300"),
Runcobo::RouteHandler.new,
Runcobo::RouteNotFoundHandler.new,
] of HTTP::Handler/assets/css/app.css reads public/css/app.css. The wrapper reuses Crystal's
static file handler for content types, conditional caching, precompressed files
and range reads. Directory listing is disabled; paths and symlinks must remain
inside the configured directory. A missing directory can be created later.
Unmatched prefixes and missing files fall through to the next handler; missing
HEAD responses return 404 without a body. Static mounts accept GET and HEAD,
with no body sent for HEAD. Other methods return 405 with Allow: GET, HEAD.
This does not add implicit HEAD routes to actions. The optional cache_control
value is applied only to existing files and their conditional responses, not
missing files or rejected methods.
Receive files in an ordinary action:
Dir.mkdir_p("storage/uploads")
class Files::Create < BaseAction
post "/files"
call do
file = upload("file")
name = Random::Secure.hex(16)
file.save("storage/uploads/#{name}")
render_json({name: name, filename: file.filename, size: file.size})
end
endupload("file") returns one Runcobo::UploadFile; missing or repeated single-file
fields use the normal validation error hook. uploads("files") returns an array,
or an empty array when absent. Ordinary fields continue to use validate(Contract)
or a declared form contract. Multipart input is parsed once regardless of the
access order, and file parts do not appear as unknown ordinary fields.
The object exposes filename, content_type, actual byte size, and a seekable
temporary file. save(path) copies the entire file without changing the read
position; the application prepares the directory and chooses the destination.
Names and content types come from client metadata and do not determine storage paths.
Files go directly to temporary files. The entire request, including fields,
headers and multipart epilogues, uses max_request_body_size; the default is
1,048,576 bytes. Override it for larger uploads. Each multipart request also has
fixed limits of 100 files and 1,000 fields. Limits return 413 and malformed input
returns 400 through the existing validation hook.
The call do ... end lifecycle closes and deletes temporary files on normal
completion, early returns and exceptions. Failed parsing also cleans files
already received. Files persisted by save remain; retain a saved file rather
than a request-owned temporary file for work after the action returns. File
storage policy, image processing and business validation remain in the application.
Requests expose base_url, scheme, protocol, host, port, ssl? and
remote_ip. The base address contains the scheme, host and non-default port,
without the path or query. The transport determines the scheme for direct
connections, including encrypted listeners. The peer address is retained on
the server context; remote_ip is the resolved client address, or nil when
there is no network peer.
proxy_config = Runcobo::ProxyConfig.new(
trusted_proxies: ["127.0.0.1", "10.0.0.0/8", "2001:db8::/48"],
)
Runcobo.start(proxy_config: proxy_config)No proxies are trusted by default. Only a trusted direct peer can supply
X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port or X-Forwarded-For.
The last scheme, host and port values describe the nearest trusted proxy's
external request. Only http and https schemes are accepted. Invalid metadata
falls back to the direct request/transport. Missing or invalid Host values
fall back to the local listener address, or localhost for standalone requests.
Default ports are omitted from base_url; literal hosts with colons are bracketed.
The client address chain is walked from right to left, starting at the direct
peer, until an untrusted address is reached. Values to its left are ignored.
An invalid address encountered while traversing the trusted suffix causes a
fallback to the direct peer. Address headers must contain literal addresses
without ports. Forwarded and Client-Ip are not used; normalize the proxy
configuration to the documented X-Forwarded-* header family.
Provider-specific single-address headers are opt-in:
proxy_config = Runcobo::ProxyConfig.new(
trusted_proxies: ["127.0.0.1"],
client_ip_header: "CF-Connecting-IP",
)This header takes precedence when present; an invalid value falls back to the
peer. When absent, the ordinary address chain is used. Neither CF-Connecting-IP
nor X-Real-IP is read automatically. Configure trusted proxies to strip or
overwrite client-supplied forwarding and provider headers with correct external
request information.
Runcobo::Server installs RequestInfoHandler before application handlers,
including custom handler lists. A supplied RequestInfoHandler takes precedence
over the server's implicit handler and configuration. When composing a chain
directly with HTTP::Server.build_middleware, install
Runcobo::RequestInfoHandler.new(proxy_config) before handlers that use request
metadata. Configuration is scoped to each server/handler. Fixed public addresses
belong to application link generation; they do not change request.base_url.
Crystal's existing hostname and deprecated host_with_port retain their native
raw-header behavior; use host, port and base_url for resolved metadata.
Runcobo::Pagination holds the page, page size and 64-bit offset used by queries
and templates. Validate request fields with a contract before constructing it:
pagination = Runcobo::Pagination.new(
input.page,
input.per_page,
default_per_page: 20,
max_per_page: 100,
)
# Use pagination.offset and pagination.per_page in database queries.
page_items = pagination.slice(items)The default page is 1, the default page size is 20 and the maximum page size is
100. These page size settings can be configured per instance; they must be
positive and the default must not exceed the maximum. Missing or nonpositive
pages become 1, pages above Int32::MAX are capped, missing or nonpositive page
sizes use the configured default, and larger sizes use the configured maximum.
slice returns an empty array for a page beyond the list, including very large
offsets. This normalization does not replace request contract validation.
Configure the view root once, before declaring actions:
Runcobo.views "src/actions", engine: :jbuilder,
layout_dir: "src/web/templates/layouts"
abstract class AppAction < BaseAction
layout "application"
end
class Notes::Create < AppAction
post "/notes"
call do
title = "Hello"
render status_code: 201
end
endThis renders src/actions/notes/create.jbuilder with
src/web/templates/layouts/application.jbuilder. Configure engine: :water
to use Water by default. Without configuration the defaults are src/views,
jbuilder, and src/views/layouts. The configuration also registers jbuilder
partials, so a separate Jbuilder.templates declaration is unnecessary.
renderinfers the template from the action's qualified class name.render :createorrender "create"selects a template in the current action namespace. Names containing/, such as"notes/create", are relative to the configured root.dir: "other/templates"sets an explicit root and skips the action namespace.- Layouts inherit from the action class.
layout: "alternative"overrides one render;layout: nildisables it. Declarelayout nilto disable it for an action class. The existinglayout ""convention is also supported. engine: :waterorengine: :jbuilderoverrides the configured engine.
Use render_to_string with the same options to obtain a string without changing
the response body, status or headers. Inside an action it infers the same path and
inherits the same layout as render. In helpers, provide a root-relative name:
body = Runcobo.render_to_string "notes/partials/event", layout: nilThe helper entry has no action context and defaults to no layout. Templates retain
access to local variables in the calling scope. Paths, engines and layouts are
checked at compile time. The explicit render_jbuilder and render_water
entries remain available; their template names are relative to the configured
root, including names without /.
class WaterExample < BaseAction
get "/water_example"
call do
render_water "examples/index"
end
endclass PlainExample < BaseAction
get "/plain_example"
call do
render_plain "Hello World!"
end
endclass BodyExample < BaseAction
get "/body_example"
call do
render_body "Hello World!"
end
endclass JbuilderExample < BaseAction
get "/jbuilder_example"
call do
render_jbuilder "examples/index"
end
endRuncobo renders JSON by Jbuilder, renders HTML by Water. Jbuilder is a template engine designed for json using plain Crystal. Water is a template engine designed for html using plain Crystal.
All methods or variables defined in the action are available in the views. This is because the views are compiled in the same scope as the action.
You can override the default layout conventions in your actions by using the layout declaration. For example:
class BaseAction
layout "application"
#...
endRegister reusable jbuilder templates once with Runcobo.views "src/views"
(or Jbuilder.templates "src/views" when using the explicit engine entries
without view configuration).
Declare their named locals on the first line and pass those locals explicitly.
Partials run in separate methods on the current builder, so they do not capture
or overwrite the action's local variables. Paths and locals are checked at build
time; running the compiled application does not read template files.
For example,
src/views/books/index.jbuilder
json.array! "books", books do |json, book|
json.partial! "books/_base_book", book: book
endsrc/views/books/_base_book.jbuilder
# locals: book
json.book_id book.id
json.author book.author
json.name book.name
json.published_at book.published_atsrc/controllers/books/index.cr
class Books::Index < BaseAction
get "/books"
call do
books = Book.all
render_jbuilder "books/index"
end
endsrc/views/books/index.jbuilder
json.array! "books", books do |json, book|
json.book_id book.id
json.author book.author
json.name book.name
json.published_at book.published_at
endThen, output a JSON string.
{
"books": [{
"book_id": 1,
"author": "David",
"name": "Crystal Programming",
"published_at": "2020-08-08T20:00:00+00:00"
}]
}src/views/books/index.jbuilder
json.array! "books", books do |json, book|
{{ read_file("src/views/books/_base_book.jbuilder").id }}
endsrc/views/books/_base_book.jbuilder
json.book_id book.id
json.author book.author
json.name book.name
json.published_at book.published_atsrc/controllers/books/index.cr
class Books::Index < BaseAction
get "/books"
call do
books = Book.all
render_water "books/index"
end
endsrc/views/books/index.water
table %|class="table table-hover"| {
thead {
tr {
th "ID"
th "Author"
th "Name"
th "Published At"
}
}
tbody {
books.each do |book|
tr {
td book.id
td book.author
td book.name
td book.published_at
}
end
}
}Then, output a HTML string.
<table class="table table-hover">
<thead>
<tr>
<th>ID</th>
<th>Author</th>
<th>Name</th>
<th>Published At</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>David</td>
<td>Crystal Programming</td>
<td>2020-08-02 14:07:41 +08:00</td>
</tr>
</tbody>
</table>src/views/books/index.jbuilder
{{ read_file("src/views/books/table.water").id }}src/views/books/table.water
table %|class="table table-hover"| {
thead {
tr {
th "ID"
th "Author"
th "Name"
th "Published At"
}
}
tbody {
books.each do |book|
tr {
td book.id
td book.author
td book.name
td book.published_at
}
end
}
}Runcobo supports crsql through a complete PostgreSQL example. Request contracts produce typed inputs, named queries generate typed data-access methods, and actions explicitly construct their responses. The example includes partial updates with presence flags and a two-write transaction with rollback on a duplicate book identifier.
Database access is optional: add the pg driver to applications that need it.
The framework does not create a global pool or require a database for ordinary
routes. crsql and sqlc are build-time tools; a compiled application runs with its
generated queries and database driver alone.
Use an application-specific subclass of Runcobo::RouteHandler and override its
protected build_action(action_class, context) hook to attach a typed query
object or service to your own base action. The example opens one application
pool, passes a store through that handler, and closes the pool when the server
scope ends. Caller-managed transactions use queries.with_transaction(tx);
transactional work always uses that store instead of checking out another pool
connection.
Custom handlers work with Runcobo.start(handlers: ...) and
Runcobo::Server.new(handlers: ...). They can also be assigned before sockets
are bound. See the example for setup, schema initialization, generation,
running requests, and dedicated-database tests.
The development branch requires Crystal >= 1.22.0 and < 2.0.0, with Shards
and Make installed. Automated checks run on Crystal 1.22.0 and 1.22.3.
Installation and development checks require read access to the private
shootingfly/request-validation runtime dependency. Generator development checks
also require the private shootingfly/crsql repository. Generation uses sqlc
1.31.1; database tests use a dedicated PostgreSQL database.
git clone https://github.com/runcobo/runcobo.git
cd runcobo
make checkIf you already have a local clone of request-validation, create the ignored
shard.override.yml in the Runcobo root instead of downloading it:
dependencies:
request_validation:
path: ../request-validation
crsql:
path: ../crsqlAutomated checks use separate read-only deploy keys in the repository secrets
REQUEST_VALIDATION_SSH_KEY and CRSQL_SSH_KEY to check out pinned dependencies.
They use a temporary dependency override, without embedding credentials in the
shard manifest. Full checks on forks need equivalent private-repository access;
GitHub does not expose upstream secrets to fork pull requests.
make check installs dependencies, runs the specs, compiles the example application,
checks formatting in src and spec, builds bin/runcobo, and checks its --version and --help
commands. It does not install anything into system directories. The same
command runs for pushes and pull requests targeting main. Automated checks
also run make generate-check and make integration; see the database example
for preparing the dedicated test database.
For individual tasks:
make build # Build bin/runcobo locally; also the default for make
make test # Install dependencies and run specs
make examples-check # Compile the example applications without linking
make generate # Regenerate the crsql example queries (requires sqlc)
make generate-check # Check generation against the committed file
make integration # Run with DATABASE_URL pointing to runcobo_crsql_test
make format # Apply formatting to src and spec
make format-check # Check formatting without changing files
make help # List development commandsDependencies and the local dependency lock file (shard.lock) are ignored in
this library repository. Applications should commit their own lock files.
To install the executable explicitly, use make install. The default
installation directory is /usr/local/bin; use an existing writable prefix
to avoid requiring elevated permissions:
make install INSTALL_DIR="$HOME/.local/bin"Add that directory to your shell's command search path before running runcobo.
- Fork it (https://github.com/runcobo/runcobo/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Write specs and run
make check(usemake formatto apply formatting) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
- Shootingfly - creator and maintainer
Request-level contracts retain field decoding modes when combining sources: query and route fields use parameter conversions, while structured body fields retain strict native types. Body fields replace query fields and route fields take precedence. Validation, constraints and cross-field rules run once on the merged input. Explicit source contracts continue to validate only their declared source.
REUSE_PORT accepts true or false and defaults to false when absent. Other
values fail at startup rather than enabling port reuse through string presence.
A certificate and private key must be configured together. Supplying only one
fails before binding a socket. Response observers can use headers_sent? to
distinguish a failure before headers from an interrupted response stream.
Server shutdown stops admission and keeps listen blocked until active handlers
finish, before callers release their dependencies. shutdown_timeout defaults to
30 seconds and can be supplied to Runcobo.start or the server instance. Requests
exceeding the grace period are reported; repeated close calls are harmless.
UploadFile#save writes to a temporary file beside the destination and renames it
only after copying succeeds. A failed copy removes its temporary output and
preserves an existing destination.
Framework logs use the global Crystal logging builder under the runcobo source.
Log.setup, Log.setup_from_env, and Log.capture control both framework and
application output. Runcobo.logger now configures that shared pipeline. The
native LogHandler owns request IDs, elapsed time and completion/failure logs;
query values are excluded. request.request_id is now String? to preserve opaque
incoming request IDs and matches the X-Request-Id response header.