blest 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0a8f112cb397ac2725175231766a0ca838e9ce898180cfc8be6e59e7fa498b8
+  data.tar.gz: b9f91cdfb82e5058d889fd6abddc8f14248c567567a3cb0acbd673d04b99f84c
+SHA512:
+  metadata.gz: 7fc3d8ae042c5b9dc96cb9fda9edeada1e34c26d1d08e890e72359c74f675e7c874b3c71ec78e4c056a8aaa886081be3374d87a46e22f86fd8689019149a9c8f
+  data.tar.gz: a862d3210e033fdf7b9d71b6b65b710a169955b49804df64aacfe0aacc73486f28e42a5dbf37994e66fa7a66ade5a39bbb2ecb5984941f5cf2c7284cc87308a8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 JHunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# BLEST Ruby
+
+The Ruby reference implementation of BLEST (Batch-able, Lightweight, Encrypted State Transfer), an improved communication protocol for web APIs which leverages JSON, supports request batching and selective returns, and provides a modern alternative to REST.
+
+To learn more about BLEST, please refer to the white paper: https://jhunt.dev/BLEST%20White%20Paper.pdf
+
+For a front-end implementation in React, please visit https://github.com/jhuntdev/blest-react
+
+## Features
+
+- Built on JSON - Reduce parsing time and overhead
+- Request Batching - Save bandwidth and reduce load times
+- Compact Payloads - Save more bandwidth
+- Selective Returns - Save even more bandwidth
+- Single Endpoint - Reduce complexity and improve data privacy
+- Fully Encrypted - Improve data privacy
+
+<!-- ## Installation
+
+Install BLEST Python from PyPI.
+
+```bash
+python3 -m pip install blest
+``` -->
+
+## Usage
+
+Use the `create_request_handler` function to create a request handler suitable for use in an existing Python application. Use the `create_http_server` function to create a standalone HTTP server for your request handler.
+
+<!-- Use the `create_http_client` function to create a BLEST HTTP client. -->
+
+### create_request_handler
+
+```ruby
+require 'socket'
+require 'json'
+require './blest.rb'
+
+server = TCPServer.new('localhost', 8080)
+
+# Create some middleware (optional)
+auth_middleware = ->(params, context) {
+  if params[:name].present?
+    context[:user] = {
+      name: params[:name]
+    }
+    nil
+  else
+    raise RuntimeError, "Unauthorized"
+  end
+}
+
+# Create a route controller
+greet_controller = ->(params, context) {
+  {
+    greeting: "Hi, #{context[:user][:name]}!"
+  }
+}
+
+# Create a router
+router = {
+  greet: [auth_middleware, greet_controller]
+}
+
+# Create a request handler
+handler = create_request_handler(router)
+
+puts "Server listening on port 8080"
+
+loop do
+
+  client = server.accept
+
+  request = client.gets
+  if request.nil?
+    client.close
+  else
+
+    method, path, _ = request.split(' ')
+
+    if method != 'POST' 
+      client.puts "HTTP/1.1 405 Method Not Allowed"
+      client.puts "\r\n"
+    elsif path != '/'
+      client.puts "HTTP/1.1 404 Not Found"
+      client.puts "\r\n"
+    else
+      content_length = 0
+      while line = client.gets
+        break if line == "\r\n"
+        content_length = line.split(': ')[1].to_i if line.start_with?('Content-Length')
+      end
+
+      body = client.read(content_length)
+      data = JSON.parse(body)
+
+      context = {
+        headers: request.headers
+      }
+
+      # Use the request handler]
+      result, error = handler.(data, context)
+
+      if error
+          response = error.to_json
+          client.puts "HTTP/1.1 500 Internal Server Error"
+          client.puts "Content-Type: application/json"
+          client.puts "Content-Length: #{response.bytesize}"
+          client.puts "\r\n"
+          client.puts response
+      elsif result
+          response = result.to_json
+          client.puts "HTTP/1.1 200 OK"
+          client.puts "Content-Type: application/json"
+          client.puts "Content-Length: #{response.bytesize}"
+          client.puts "\r\n"
+          client.puts response
+      else
+          client.puts "HTTP/1.1 204 No Content"
+      end
+    end
+
+    client.close
+
+  end
+end
+```
+
+### create_http_server
+
+```ruby
+require 'socket'
+require 'json'
+require './blest.rb'
+
+# Create some middleware (optional)
+auth_middleware = ->(params, context) {
+  if params[:name].present?
+    context[:user] = {
+      name: params[:name]
+    }
+    nil
+  else
+    raise RuntimeError, "Unauthorized"
+  end
+}
+
+# Create a route controller
+greet_controller = ->(params, context) {
+  {
+    greeting: "Hi, #{context[:user][:name]}!"
+  }
+}
+
+# Create a router
+router = {
+  greet: [auth_middleware, greet_controller]
+}
+
+# Create a request handler
+handler = create_request_handler(router)
+
+# Create the server
+server = create_http_server(handler, { port: 8080 })
+
+# Run the server
+server.()
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

data/lib/blest.rb

@@ -0,0 +1,281 @@
+require 'socket'
+require 'json'
+
+def create_http_server(request_handler, options = nil)
+  
+  def parse_request(request_line)
+    method, path, _ = request_line.split(' ')
+    { method: method, path: path }
+  end
+
+  def parse_headers(client)
+    headers = {}
+
+    while (line = client.gets.chomp)
+      break if line.empty?
+
+      key, value = line.split(':', 2)
+      headers[key] = value.strip
+    end
+
+    headers
+  end
+
+  def parse_body(client, content_length)
+    body = ''
+  
+    while content_length > 0
+      chunk = client.readpartial([content_length, 4096].min)
+      body += chunk
+      content_length -= chunk.length
+    end
+  
+    body
+  end
+
+  def build_response(status, headers, body)
+    response = "HTTP/1.1 #{status}\r\n"
+    headers.each { |key, value| response += "#{key}: #{value}\r\n" }
+    response += "\r\n"
+    response += body
+    response
+  end
+
+  def handle_request(client, request_handler)
+    request_line = client.gets
+    return unless request_line
+  
+    request = parse_request(request_line)
+    
+    headers = parse_headers(client)
+    
+    cors_headers = {
+      'Access-Control-Allow-Origin' => '*',
+      'Access-Control-Allow-Methods' => 'POST, OPTIONS',
+      'Access-Control-Allow-Headers' => 'Content-Type'
+    }
+  
+    if request[:path] != '/'
+      response = build_response('404 Not Found', cors_headers, '')
+      client.print(response)
+    elsif request[:method] == 'OPTIONS'
+      response = build_response('204 No Content', cors_headers, '')
+      client.print(response)
+    elsif request[:method] == 'POST'
+
+      content_length = headers['Content-Length'].to_i
+      body = parse_body(client, content_length)
+      
+      begin
+        json_data = JSON.parse(body)
+        context = {
+          'headers' => headers
+        }
+
+        response_headers = cors_headers.merge({
+          'Content-Type' => 'application/json'
+        })
+
+        result, error = request_handler.(json_data, context)
+
+        if error
+            response_json = error.to_json
+            response = build_response('500 Internal Server Error', response_headers, response_json)
+            client.print response
+        elsif result
+            response_json = result.to_json
+            response = build_response('200 OK', response_headers, response_json)
+            client.print response
+        else
+          response = build_response('500 Internal Server Error', response_headers, { 'message' => 'Request handler failed to return a result' }.to_json)
+          client.print response
+        end
+
+      rescue JSON::ParserError
+        response = build_response('400 Bad Request', cors_headers, '')
+      end
+
+    else
+      response = build_response('405 Method Not Allowed', cors_headers, '')
+      client.print(response)
+    end
+    client.close()
+  end
+
+  run = ->() do
+
+    port = options&.fetch(:port, 8080) if options.is_a?(Hash)
+    port ||= 8080
+
+    server = TCPServer.new('localhost', 8080)
+    puts "Server listening on port #{port}"
+
+    loop do
+      client = server.accept
+      Thread.new { handle_request(client, request_handler) }
+    end
+
+  end
+
+  return run
+end
+
+def create_request_handler(routes, options = nil)
+  if options
+    puts 'The "options" argument is not yet used, but may be used in the future'
+  end
+
+  def handle_result(result)
+    return [result, nil]
+  end
+
+  def handle_error(code, message)
+    return [nil, { 'code' => code, 'message' => message }]
+  end
+
+  def route_not_found(_, _)
+    raise 'Route not found'
+  end
+
+  def route_reducer(handler, request, context = nil)
+    safe_context = context ? context.clone : {}
+    result = nil
+
+    if handler.is_a?(Array)
+      handler.each_with_index do |func, i|
+        temp_result = func.call(request[:parameters], safe_context)
+
+        if i == handler.length - 1
+          result = temp_result
+        else
+          raise 'Middleware should not return anything but may mutate context' if temp_result
+        end
+      end
+    else
+      result = handler.call(request[:parameters], safe_context)
+    end
+
+    raise 'The result, if any, should be a JSON object' if result && !(result.is_a?(Hash))
+
+    result = filter_object(result, request[:selector]) if result && request[:selector]
+    return [request[:id], request[:route], result, nil]
+  rescue StandardError => error
+    return [request[:id], request[:route], nil, { message: error.message }]
+  end
+
+  def filter_object(obj, arr)
+    if arr.is_a?(Array)
+      filtered_obj = {}
+      arr.each do |key|
+        if key.is_a?(String)
+          if obj.key?(key.to_sym)
+            filtered_obj[key.to_sym] = obj[key.to_sym]
+          end
+        elsif key.is_a?(Array)
+          nested_obj = obj[key[0].to_sym]
+          nested_arr = key[1]
+          if nested_obj.is_a?(Array)
+            filtered_arr = []
+            nested_obj.each do |nested_item|
+              filtered_nested_obj = filter_object(nested_item, nested_arr)
+              if filtered_nested_obj.keys.length > 0
+                filtered_arr << filtered_nested_obj
+              end
+            end
+            if filtered_arr.length > 0
+              filtered_obj[key[0].to_sym] = filtered_arr
+            end
+          elsif nested_obj.is_a?(Hash)
+            filtered_nested_obj = filter_object(nested_obj, nested_arr)
+            if filtered_nested_obj.keys.length > 0
+              filtered_obj[key[0].to_sym] = filtered_nested_obj
+            end
+          end
+        end
+      end
+      return filtered_obj
+    end
+    return obj
+  end
+
+  route_regex = /^[a-zA-Z][a-zA-Z0-9_\-\/]*[a-zA-Z0-9_\-]$/
+
+  handler = ->(requests, context = {}) do
+    if !requests || !requests.is_a?(Array)
+      return handle_error(400, 'Request body should be a JSON array')
+    end
+
+    unique_ids = []
+    promises = []
+
+    requests.each do |request|
+      if !request.is_a?(Array)
+        return handle_error(400, 'Request item should be an array')
+      end
+
+      id = request[0]
+      route = request[1]
+      parameters = request[2] || nil
+      selector = request[3] || nil
+
+      if !id || !id.is_a?(String)
+        return handle_error(400, 'Request item should have an ID')
+      end
+
+      if !route || !route.is_a?(String)
+        return handle_error(400, 'Request item should have a route')
+      end
+
+      if !route_regex.match?(route)
+        route_length = route.length
+        if route_length < 2
+          return handle_error(400, 'Request item route should be at least two characters long')
+        elsif route[-1] == '/'
+          return handle_error(400, 'Request item route should not end in a forward slash')
+        elsif !/[a-zA-Z]/.match?(route[0])
+          return handle_error(400, 'Request item route should start with a letter')
+        else
+          return handle_error(
+            400,
+            'Request item route should contain only letters, numbers, dashes, underscores, and forward slashes'
+          )
+        end
+      end
+
+      if parameters && !parameters.is_a?(Hash)
+        return handle_error(400, 'Request item parameters should be a JSON object')
+      end
+
+      if selector && !selector.is_a?(Array)
+        return handle_error(400, 'Request item selector should be a JSON array')
+      end
+
+      if unique_ids.include?(id)
+        return handle_error(400, 'Request items should have unique IDs')
+      end
+
+      unique_ids << id
+
+      route_handler = routes[route] || routes[route.to_sym] || method(:route_not_found)
+
+      request_object = {
+        id: id,
+        route: route,
+        parameters: parameters,
+        selector: selector,
+      }
+
+      promises << route_reducer(route_handler, request_object, context)
+    end
+
+    results = []
+
+    promises.each do |result|
+      results << result
+    end
+
+    return handle_result(results)
+  end
+
+  return handler
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: blest
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- JHunt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-07-10 00:00:00.000000000 Z
+dependencies: []
+description: The Ruby reference implementation of BLEST (Batch-able, Lightweight,
+  Encrypted State Transfer), an improved communication protocol for web APIs which
+  leverages JSON, supports request batching and selective returns, and provides a
+  modern alternative to REST.
+email:
+- blest@jhunt.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/blest.rb
+homepage: https://blest.jhunt.dev
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: The Ruby reference implementation of BLEST
+test_files: []