CyberTrain API
The methods an application calls: in controllers, models, migrations,
config/routes.rb, config/app.rb and tests. New to CyberTrain? Start with
the tutorial.
The guides cover the rest: installing and the CLI,
how it works and the differences from Rails,
models, requests,
configuration,
background work and operations,
outbound HTTP, WebSocket feeds and e-mail
and testing.
These pages are generated by YARD from the
framework’s source, cybertrain/, and only from what is marked as part of
the public API; everything else there is internal. Some of the API is not in
the framework at all: spin run gen writes it into each application’s
gen/ directory, and it is documented here through the classes
examples/blog
generates (Article, ArticleRelation, Gen::UrlHelpers).
Where things are
| You write | Reference |
|---|---|
class ArticlesController < ApplicationController |
Cybertrain::Controller: before_action, skip_before_action, rate_limit (Cybertrain::RateLimit), rescue_from, render, redirect_to, head |
user.password = ..., user.authenticate(...) (from cybertrain generate authentication) |
Cybertrain::Password: hash, verify?, needs_rehash?, iterations= |
params[:id], params.require(:article).permit(...) |
Cybertrain::Params |
session[...], flash[...] |
Cybertrain::Session, Cybertrain::Flash |
request.header(...), request.client_ip, response.set_header(...), cookies |
Cybertrain::Request, Cybertrain::Response, Cybertrain::Cookies |
Article.where(...).order(...).to_a, Article.find(id) |
Article and ArticleRelation (generated), Cybertrain::Relation |
article.save, article.update(...), article.errors |
Cybertrain::Model, Cybertrain::Errors |
validates, before_save { \|r\| ... } in app/models/ |
Cybertrain::Model.validates, Cybertrain::Model.before_save and the other callbacks |
article.comments, comment.article |
Article#comments, Comment#article (from foreign keys) |
config/routes.rb |
Cybertrain::Routes.draw, Cybertrain::Gen::Mapper (resources, resource, get …) |
article_path(@article) |
Gen::UrlHelpers (generated), Cybertrain.url_root |
db/migrate/*.rb |
Cybertrain::Migration::Base, Cybertrain::Schema::TableDef |
Cybertrain::WebSocket.subscribe("trades", url).on_open { ... }.on_message { ... } in config/app.rb |
Cybertrain::WebSocket (require "cybertrain/websocket"): Cybertrain::WebSocket.subscribe, Cybertrain::WebSocket::Subscription, Cybertrain::WebSocket::Connection, Cybertrain::WebSocket.feed_status; one connection: Cybertrain::WebSocket::Client; Cybertrain::Background |
config/app.rb |
Cybertrain.configure, Cybertrain::Config |
test/*.rb |
Cybertrain::Test, Cybertrain::Test::Client, and the assertions below |
app/views/**/*.html.erb |
Template language: helpers (link_to, form_with, …), the form builder and what a template may call |
| HTML from Ruby | Cybertrain::Html, Cybertrain::SafeString |
Exceptions you will meet
| Exception | Raised by | Unhandled, the request gets |
|---|---|---|
| Cybertrain::RecordNotFound | find, Cybertrain::Model#reload |
500; the generated ApplicationController rescues it to a 404 |
| Cybertrain::RecordInvalid | Cybertrain::Model#save! | 500 |
| Cybertrain::Params::ParameterMissing | Cybertrain::Params#require | 400 |
| Cybertrain::BodyUndecodable, Cybertrain::BodyTooLarge | Cybertrain::Request#decoded_body on a corrupt or unsupported Content-Encoding, or a body that would inflate past its size limit |
400 |
ArgumentError |
order with anything but column [ASC\|DESC], render with the wrong options |
500 |
Cybertrain::DB::Error |
SQLite refusing a query (a NOT NULL or foreign key constraint, a missing column) | 500 |
Cybertrain::Controller.rescue_from matches the exception’s class exactly.
In production a bare error response is replaced by public/<status>.html
when that file exists; in development a 500 shows the exception’s class,
message and template line.
Assertions
Top-level methods for test/*.rb (see Cybertrain::Test):
| Assertion | Passes when |
|---|---|
assert(condition, message = ...) |
the condition is truthy |
refute(condition, message = ...) |
it is false or nil |
assert_equal(expected, actual) |
expected == actual |
assert_nil(actual) |
it is nil |
assert_includes(haystack, needle) |
a String contains it, or an Array includes it |
assert_raises("ClassName") { ... } |
the block raises a matching StandardError; returns its message |
flunk(message) |
never |
assert_response(response, :ok) |
the status matches (an Integer, or :success, :redirect, :not_found, …) |
assert_redirected_to(response, "/path") |
it is a redirect to exactly that Location |
assert_response and assert_redirected_to come with
require "cybertrain/test/client". Each is documented on the
Top Level Namespace page.
Webhooks and e-mail the code under test sends are received in-process by
Cybertrain::Test::HttpReceiver (require "cybertrain/test/http_receiver")
and Cybertrain::Test::SmtpReceiver (require "cybertrain/test/smtp_receiver");
a WebSocket feed it consumes is played by Cybertrain::Test::WebSocketReceiver
(require "cybertrain/test/websocket_receiver").
Conventions on these pages
- Signatures and behaviour are those of the current
mainbranch; an application pins its framework version inspin.lock. - Many methods’ descriptions end with notes on the Spinel constraint behind a design choice. They explain the framework’s code; you can skip them.