From 6d33fa3a0e2112a7a58a4d900df1b7660fca1f25 Mon Sep 17 00:00:00 2001 From: Yessiest Date: Sun, 28 Apr 2024 12:06:00 +0400 Subject: [PATCH] updated README --- LAYOUT.md | 86 --------------------------------------------- README.md | 92 +++++++++++++++++++++++++++++++++++++++---------- lib/landline.rb | 4 +-- 3 files changed, 75 insertions(+), 107 deletions(-) delete mode 100644 LAYOUT.md diff --git a/LAYOUT.md b/LAYOUT.md deleted file mode 100644 index 6e3df3a..0000000 --- a/LAYOUT.md +++ /dev/null @@ -1,86 +0,0 @@ -# Internal structure of Landline lib - -Note: If you want to start hacking on Landline and extending it, follow this -layout as closely as possible. - -## Core classes - -These are core classes of Landline and they are loaded as soon as the library is loaded. - -- Landline::Path [path.rb] -- Landline::PathContext [path.rb] -- Landline::Probe [probe.rb] -- Landline::ProbeContext [probe.rb] -- Landline::Node (parent of Path and Probe) [node.rb] -- Landline::Server (Rack application interface) [server.rb] -- Landline::ServerContext [server.rb] -- Landline::Request (Rack request wrapper) [request.rb] -- Landline::Response (Rack response wrapper) [response.rb] -- Landline::Pattern [pattern\_matching.rb] -- Landline::TemplateContext [tempalte.rb] -- Landline::Template (template engine interface) [template.rb] - -## Patterns - -These are classes that Landline::Pattern can interface with to create Patterns. - -- Landline::PatternMatching::ReMatch [pattern\_matching/rematch.rb] -- Landline::PatternMatching::Glob [pattern\_matching/glob.rb] - -## DSL Method mixins - -These are module mixins that add common methods to DSL bindings. - -- Landline::DSL::PathConstructors [dsl/constructors\_path.rb] -- Landline::DSL::ProbeConstructures [dsl/constructors\_probe.rb] -- Landline::DSL::CommonMethods [dsl/methods\_common.rb] -- Landline::DSL::PathMethods [dsl/methods\_path.rb] -- Landline::DSL::ProbeMethods [dsl/methods\_probe.rb] -- Landline::DSL::TemplateMethods [dsl/methods\_template.rb] - -## Utilities - -These are self-contained classes and methods that add extra functionality to Landline. - -- Landline::Util::Lookup [util/lookup.rb] -- Landline::PatternMatching [pattern\_matching/util.rb] -- Landline::Cookie (class) [util/cookie.rb] -- Landline::Error (class) [util/errors.rb] -- Landline::ParsingError (class) [util/errors.rb] -- Landline::Util (html/http utilities) [util/html.rb] -- Landline::MIME (MIME extension to type association) [util/mime.rb] -- Landline::Util::ParserSorting (functions for sorting form/query hashes) [util/parsesorting.rb] -- Landline::Util::Query (query class) [util/query.rb] -- Landline::Util::FormPart (formparser struct) [util/multipart.rb] -- Landline::Util::MultipartParser (multipart form parser) [util/multipart.rb] -- Landline::Util::HeaderRegexp (helper regexps for headers) [util/parseutils.rb] -- Landline::Util (parser methods) [util/parseutils.rb] - -## Probe subclasses - -These are reactive request handlers with their own semantics, if needed. - -- Landline::Handlers::Handler [probe/handler.rb] -- Landline::Handlers::GETHandler [probe/http\_method.rb] -- Landline::Handlers::POSTHandler [probe/http\_method.rb] -- Landline::Handlers::HEADHandler [probe/http\_method.rb] -- Landline::Handlers::PUTHandler [probe/http\_method.rb] -- Landline::Handlers::DELETEHandler [probe/http\_method.rb] -- Landline::Handlers::CONNECTHandler [probe/http\_method.rb] -- Landline::Handlers::OPTIONSHandler [probe/http\_method.rb] -- Landline::Handlers::TRACEHandler [probe/http\_method.rb] -- Landline::Handlers::PATCHHandler [probe/http\_method.rb] -- Landline::Handlers::Serve - -## Path subclasses - -These are navigation handlers with their own semantics. - -(currently none) - -## Template engine interfaces - -These are uniform interfaces for various templating engines. - -- Landline::Templates::ERB [template/erb.rb] -- Landline::Templates::Erubi [template/erubi.rb] diff --git a/README.md b/README.md index 6b55ba7..a00f600 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,15 @@ Landline is a library that provides a minimalistic DSL for creating web services. It doesn't include patterns, middleware, or anything that -could be considered application logic. It does a few things, and hopefully -it does them well: +could be considered application logic, besides the basic primitives +It does a few things, and hopefully it does them well. -- Routing HTTP requests to handlers -- Processing HTTP requests (cookies, headers, etc.) -- Filtering, preprocessing and postprocessing requests -- Creating responses from templates using various template engines -- Parsing and handling forms and queries -- Connecting multiple Landline applications together - -As such, the library is pretty thin and can be used to build more complex -applications. - -As of now it is using Rack as the webserver adapter, but ideally it -shouldn't take much work to make it run on top of any webserver. - -Landline was made mostly for fun. Ideally it will become something more, +Landline was made mostly for fun. ~~Ideally it will become something more, but as of yet it's just an experiment revolving around Ruby Metaprogramming -and its DSL capabilities. +and its DSL capabilities.~~ Since then, it has somewhat matured, and while +it's still not entirely advisable to use in production due to the experimental +nature of the framework, you're free to test it, see if it works, and if it +doesn't, supply (hopefully constructive) criticism and/or suggestions. ## Examples @@ -85,7 +75,7 @@ end run app ``` -Static file serving +Static file serving with nginx-like syntax and file globbing (Note: index applies *only* to /var/www (to the path its defined in)) ```ruby @@ -100,7 +90,7 @@ end run app ``` -Logging on a particular path +Preprocessing requests on a subset of handlers ```ruby require 'landline' @@ -127,8 +117,72 @@ end run app ``` +Class interface with middleware support + +```ruby +require 'landline' + +class TimerMiddleware + def initialize(app) + @app = app + end + + def call(*data) + puts("Request accepted") + before = Time.now + output = @app.call(*data) + puts("Time elapsed: #{(Time.now - before) * 1000}ms") + output + end +end + +class Application < Landline::App + use TimerMiddleware + + setup do + get "/hello" do + "Hello world!" + end + end +end + +run Application.new +``` + And a lot more to be found in /examples in this repo. + +## Design goals + +Out of the box, Landline is designed to do the following: + +- Routing HTTP requests to handlers +- Processing HTTP requests (cookies, headers, etc.) +- Filtering, preprocessing, postprocessing requests +- Deferring block execution until after the request gets processed +- Creating responses from templates using various template engines +- Parsing and handling forms and queries +- Connecting multiple ~~Landline~~ Rack applications together +- Sending files using nginx-style configuration system +- A lot of basic Rack things such as plugging in middleware, BEING middleware, + or sending Rack-compatible environment to another Rack application + +As such, the library is pretty thin and can be used to build more complex +applications. This is intentional, and hopefully will remain that way. + +Additionally, there are a few extra things landline can do, which can be used +by `require`ing from the `landline/extensions` directory. Please note, however, +that some of that functionality may require additional dependencies, which +would otherwise be optional. This functionality includes: + +- PHP-like Session handling (via `landline/extensions/session`) +- Websockets (via `landline/extensions/websockets`) (coming soon) +- (Probably something else eventually) + +Landline is built entirely on Rack webserver interface, while being agnostic +to any and all underlying webservers (such as Puma, Thin, Unicorn and such). +For the foreseeable future, this design decision will not change. + ## Name The name is, quite literally, a metaphor for request routing. diff --git a/lib/landline.rb b/lib/landline.rb index a2c51c5..8b55a36 100644 --- a/lib/landline.rb +++ b/lib/landline.rb @@ -9,10 +9,10 @@ require_relative 'landline/response' require_relative 'landline/template' require_relative 'landline/app' -# Landline is a hideously simple ruby web framework +# Landline is a backend framework born as a by-product of experimentation module Landline # Landline version - VERSION = '0.11 "Decades of science" (beta)' + VERSION = '0.12 "Concrete and Gold" (pre-alpha)' # Landline branding and version VLINE = "Landline/#{Landline::VERSION} (Ruby/#{RUBY_VERSION}/#{RUBY_RELEASE_DATE})\n".freeze