gyoza-languages 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ce01cc539ead25cf2994d84a0c608f5cf306e34d5fbfed03962abe710eb4a74
+  data.tar.gz: 1311b5faa6581735afd68f06bd3b8f509d3bfef28642c35faf52ce34ee9123a7
+SHA512:
+  metadata.gz: 58bfae9ae6149021ee01bce0f03db9f97e8c8205b32307fc88d9e997dd83c0c254826c0e8c5493afaf9b0d8009d15689ef43d875f55923fa6a0ec17bc359a66f
+  data.tar.gz: 86e644db920232c5f8f31639647914761444c85f0e6eb6fededb8f459ee1d06168004d5c3998c688536a994f5a9e33fe412382c8aefc9419626d777b6f1fa6ae

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'erb', '~> 4.0.0'
+
+gem 'rspec', '~> 3.0'
+
+gem 'github-linguist', '~> 9.0.0'
+
+gem 'puma', '~> 6.5.0'
+gem 'rack', '~> 3.1.8'
+gem 'rackup', '~> 2.2.1'

data/README.md

@@ -0,0 +1,100 @@
+<p align="center">
+  <img src="https://img.shields.io/gem/v/gyoza-languages?color=aa0000" alt="">
+  <img src="https://img.shields.io/github/actions/workflow/status/git-gyoza/gyoza-languages/gem-push.yml?label=tests" alt="">
+</p>
+
+**gyoza-languages** is a simple interface that combines the 
+speed of [GitHub Linguist](https://github.com/github-linguist/linguist)
+with the highly efficient Ruby web server [Puma](https://github.com/puma/puma).
+
+It allows to query an **HTTP Rest API** to retrieve the languages data from one
+or many repositories in a **JSON** format.
+
+| Table of Contents |
+|-------------------|
+| [Usage](#usage)   |
+| [API](#api)       |
+
+# Usage 
+
+The application requires only a few arguments, but they are essential 
+for its correct functioning.
+
+```
+A Ruby implementation of the Github linguist project with an integrated simple HTTP web server.
+
+Usage: gyoza-languages [options]
+
+    -p, --port PORT                 Starts the server with the specified port.
+    -d, --directory DIRECTORY       Manually specifies the repositories directory.
+    -h, --help                      Show this message
+
+If the -d argument is not specified, a REPOSITORIES_DIRECTORY environment variable will be necessary.
+```
+
+The most important (and mandatory) parameter is the `--directory`:
+this represents the directory where all the repositories are stored.
+Defining a correct directory is crucial for **managing** the web server **endpoints**.
+
+You can set one by either creating an **environment variable** with name
+**REPOSITORIES_DIRECTORY** or by directly specifying it using **--directory** (or **-d**).
+
+Let's assume that the folder structure you choose looks like this:
+
+```python
+repositories_directory:
+    images:
+        # a bunch of images
+    gyoza-languages:
+        # a clone of this repository
+    my_repositories:
+        super_awesome_repo:
+            # another Git repository 
+```
+
+This means that all the directories in the folder will become endpoints,
+but only a few will be valid:
+
+- `/images` will answer with **404 Not Found**, as it is not a **valid repository**;
+- `/gyoza-languages` is a valid repository and will return the correct answer;
+- `/my_repositories` is **NOT** a valid repository, even though it contains other repositories.
+  As such, it will answer with **404 Not Found**;
+- `/my_repositories/super_awesome_repo` is a valid repository.
+
+Along with that, the query parameter `branch` is also available,
+meaning that it is possible to obtain the languages count from another branch.
+An example is: `/myrepositories/super_awesome_repo?branch=dev` (if not existing, a **404 Not found**
+message will be returned).
+
+# API
+
+**gyoza-languages** also provides an **API** for general purposes and one to interact with
+the server started by the application itself.
+
+After importing the module using `require 'gyoza-languages'`, two core classes are available:
+
+- [GyozaApp](../main/lib/gyoza-languages/gyoza_app.rb).
+  This class offers five different methods that correspond to the **HTTP request methods**:
+  
+  - `get(path, query, env)`;
+  - `post(path, query, env)`;
+  - `put(path, query, env)`;
+  - `patch(path, query, env)`;
+  - `delete(path, query, env)`.
+  
+  By overriding these methods, it is possible to implement custom responses for each one
+  of the requests. The arguments passed are:
+
+  - `path`: the corresponding path in a string format;
+  - `query`: a hash that corresponds to the queried parameters;
+  - `env`: a hash comprehending all the current environment variables and more data.
+  
+  If the **HTTP method** is not among the listed above, by overriding the `call(env)`
+  function it is possible to access directly to the core responding function, and
+  retrieve the method with `env[REQUEST_METHOD]`;
+
+- [GyozaLanguageApp](../main/lib/gyoza-languages/gyoza_language_app.rb).
+  This class is the heart of the application. It extends
+  [GyozaApp](../main/lib/gyoza-languages/gyoza_app.rb) to provide support for
+  [GitHub Linguist](https://github.com/github-linguist/linguist) when a 
+  **GET request** is done to the server.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/gyoza-languages

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+
+require 'gyoza-languages'
+
+def usage
+  binary_name = GyozaLanguages::SPEC_NAME
+  env_var_name = GyozaLanguages::REPOSITORIES_DIRECTORY_ENV_NAME
+
+  puts(
+    "#{binary_name} #{GyozaLanguages::VERSION}
+#{GyozaLanguages::SPEC_DESCRIPTION}.
+
+Usage: #{binary_name} [options]
+
+    -p, --port PORT                 Starts the server with the specified port.
+    -d, --directory DIRECTORY       Manually specifies the repositories directory.
+    -h, --help                      Show this message
+
+If the -d argument is not specified, a #{env_var_name} environment variable will be necessary.")
+end
+
+def parse_arguments(parsed, args)
+  if args.length == 0
+    return
+  end
+
+  arg = args[0]
+  if arg == '-h' || arg == '--help'
+    usage
+    exit 0
+  end
+
+  if args.length == 1
+    puts("You did not specify enough arguments for argument #{arg}")
+    usage
+    exit 1
+  end
+
+  arg = arg.downcase
+  if arg == '-p'
+    arg = '--port'
+  elsif arg == '-d'
+    arg = '--directory'
+  else
+    unless arg == '--port' || arg == '--directory'
+      puts("Invalid argument: #{arg}")
+      exit 2
+    end
+  end
+
+  arg = arg[2..-1]
+  unless parsed.has_key?(arg)
+    parsed[arg] = args[1]
+  end
+  parse_arguments(parsed, args[2..-1])
+end
+
+def main(args)
+  parsed = {}
+  parse_arguments(parsed, args)
+
+  port = nil
+  if parsed.include?('port')
+    begin
+      port = parsed['port']
+      port = Integer(port)
+      if port < 1 || port > 65535
+        raise ArgumentError
+      end
+    rescue ArgumentError
+      puts("Invalid port \"#{port}\". Expected an integer between 1 and 65535")
+      exit 2
+    end
+  end
+
+  if parsed.include?('directory')
+    repo_directory = parsed['directory']
+  else
+    env_var_name = GyozaLanguages::REPOSITORIES_DIRECTORY_ENV_NAME
+    repo_directory = ENV[env_var_name]
+    if repo_directory.nil?
+      puts("No repositories directory specified.")
+      puts("You can specify one by using --directory or by defining the environment variable: #{env_var_name}")
+      exit 1
+    end
+  end
+
+  app = GyozaLanguageApp.new(repo_directory)
+  if port.nil?
+    app.start
+  else
+    app.start(port)
+  end
+end
+
+main(ARGV)

data/lib/gyoza-languages/gyoza_app.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'rugged'
+require 'linguist'
+require 'json'
+
+require_relative './string_utils'
+
+# A wrapper for a web server.
+# Works with rackup to start a new HTTP server.
+class GyozaApp
+  attr_accessor :handler, :port
+
+  # Starts a new server at the specified port
+  # using a Rackup handler which is stored in the 'handler' attribute.
+  #
+  # If the server is already running (A.K.A. the handler attribute is set),
+  # a GyozaError is raised.
+  #
+  # Arguments:
+  #   port: the port to start the server at (9172 by default)
+  def start(port = GyozaLanguages::DEFAULT_PORT)
+    if @handler.nil?
+      @handler = Rackup::Handler.default
+      @port = port
+      @handler.run(self, :Port => port)
+    else
+      raise GyozaError.serverAlreadyStarted(port)
+    end
+  end
+
+  # Stops the server.
+  #
+  # If the server is not running (A.K.A. the handler attribute is not set),
+  # a GyozaError is raised.
+  def stop
+    if @handler.nil?
+      raise GyozaError.serverNotStarted
+    else
+      @handler.stop
+      @handler = nil
+      @port = nil
+    end
+  end
+
+  # The method invoked by Puma when receiving
+  # an HTTP request.
+  #
+  # Uses get, post, put, patch and delete methods to
+  # separate requests.
+  # If the REQUEST_METHOD does not match any
+  # of the previously mentioned methods,
+  # returns the 405 HTTP status code.
+  #
+  # Arguments:
+  #   env: the environment variables at the time of receiving the request
+  def call(env)
+    method = env['REQUEST_METHOD']
+    path = env['REQUEST_PATH']
+    query = StringUtils.query_string_to_hash(env['QUERY_STRING'])
+    case method
+    when 'GET'
+      get(path, query, env)
+    when 'POST'
+      post(path, query, env)
+    when 'PUT'
+      put(path, query, env)
+    when 'PATCH'
+      patch(path, query, env)
+    when 'DELETE'
+      delete(path, query, env)
+    else
+      response 405
+    end
+  end
+
+  # The response to a GET request.
+  # By default, returns the 405 HTTP status code.
+  #
+  # Arguments:
+  #   path: the path of the repository
+  #   query: a hash containing all the query parameters
+  #   env: the environment variables at the time of receiving the request
+  protected def get(path, query, env)
+    response 405
+  end
+
+  # The response to a POST request.
+  # By default, returns the 405 HTTP status code.
+  #
+  # Arguments:
+  #   path: the path of the repository
+  #   query: a hash containing all the query parameters
+  #   env: the environment variables at the time of receiving the request
+  protected def post(path, query, env)
+    response 405
+  end
+
+  # The response to a PUT request.
+  # By default, returns the 405 HTTP status code.
+  #
+  # Arguments:
+  #   path: the path of the repository
+  #   query: a hash containing all the query parameters
+  #   env: the environment variables at the time of receiving the request
+  protected def put(path, query, env)
+    response 405
+  end
+
+  # The response to a PATCH request.
+  # By default, returns the 405 HTTP status code.
+  #
+  # Arguments:
+  #   path: the path of the repository
+  #   query: a hash containing all the query parameters
+  #   env: the environment variables at the time of receiving the request
+  protected def patch(path, query, env)
+    response 405
+  end
+
+  # The response to a DELETE request.
+  # By default, returns the 405 HTTP status code.
+  #
+  # Arguments:
+  #   path: the path of the repository
+  #   query: a hash containing all the query parameters
+  #   env: the environment variables at the time of receiving the request
+  protected def delete(path, query, env)
+    response 405
+  end
+
+  # Formats a new HTTP response from the given HTTP status code.
+  #
+  # Arguments:
+  #   code: the status code
+  #   body: the data sent to the client. The method will first try to
+  #         convert the data in Json (unless it is String). If it fails,
+  #         it will return the data accordingly
+  #   headers: the headers to pass to the response.
+  #            By default, this value is empty, and will be populated
+  #            with the server name and current date
+  def response(code, body = nil, headers = {})
+    if code < 100 || code > 599
+      raise GyozaError.invalidStatusCode(code)
+    end
+
+    actual_headers = {}
+    headers.each do |key, value|
+      actual_headers[key.to_s.titleize] = value
+    end
+    headers = actual_headers
+
+    headers['Server'] = GyozaLanguages::SERVER_NAME
+    headers['Date'] = Time.now.utc.strftime('%a, %d %b %Y %H:%M:%S GMT')
+
+    unless body.nil?
+      if body.is_a?(String)
+        headers['Content-Type'] = 'text/plain'
+      else
+        body = JSON.dump(body)
+        headers['Content-Type'] = 'application/json'
+      end
+    end
+
+    [code, headers, body.nil? ? [] : [body]]
+  end
+
+end

data/lib/gyoza-languages/gyoza_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Represents a general RuntimeError during the application execution
+class GyozaError < RuntimeError
+
+  def self.invalidDirectory(directory)
+    return GyozaError.new("\"#{directory}\" is not a valid directory.")
+  end
+
+  def self.serverAlreadyStarted(port)
+    return GyozaError.new("Server is already listening on port #{port}.")
+  end
+
+  def self.serverNotStarted
+    return GyozaError.new('Server has not been started yet.')
+  end
+
+  def self.invalidStatusCode(code)
+    return GyozaError.new("Invalid status code #{code}. Expecting value between 100 and 599.")
+  end
+
+end
+

data/lib/gyoza-languages/gyoza_language_app.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'rugged'
+require 'linguist'
+
+require_relative 'gyoza_app'
+
+# An implementation of GyozaApp that works with GitHub linguist.
+class GyozaLanguageApp < GyozaApp
+  attr_accessor :repo_directory
+
+  # Initializes the Gyoza Language App.
+  #
+  # Arguments:
+  #   repo_directory: the location where all the repositories are stored
+  def initialize(repo_directory)
+    if File.directory?(repo_directory)
+      @repo_directory = repo_directory
+    else
+      raise GyozaError.invalidDirectory(repo_directory)
+    end
+  end
+
+  def start(port = GyozaLanguages::DEFAULT_PORT)
+    puts("Starting gyoza-languages server on port #{port} with repositories directory: #{@repo_directory}")
+    super
+  end
+
+  # Checks in the repositories directory for the given repository
+  # in the path. If found, uses GitHub linguist to compute the
+  # used languages and returns them in a Json format.
+  # Otherwise, 404 'Not Found' is returned.
+  #
+  # Arguments:
+  #   path: the path of the repository
+  #   query: a hash of arguments. If the "branch" argument is specified, then
+  #          the languages will be looked for that particular branch. However,
+  #          if not found a 404 'Not Found' error is returned
+  #   env: the environment variables at the time of receiving the request
+  protected def get(path, query, env)
+    repository = "#{@repo_directory}/#{path}"
+    unless File.directory?(repository)
+      return not_found('repository', path)
+    end
+
+    begin
+      repo = Rugged::Repository.new(repository)
+    rescue Rugged::RepositoryError
+      return not_found('repository', path)
+    end
+
+    target_id = repo.head.target_id
+    if query.include? 'branch'
+      begin
+        branch = query['branch']
+        target_id = repo.rev_parse_oid(branch)
+      rescue Rugged::ReferenceError
+        return not_found('branch', branch)
+      end
+    end
+
+    project = Linguist::Repository.new(repo, target_id)
+    languages = project.languages
+
+    response(200, languages)
+  end
+
+  private def not_found(type, name)
+    response(404, {
+      'message' => "Could not find #{type}: #{name}"
+    })
+  end
+
+end

data/lib/gyoza-languages/string_utils.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# A collection of utilities for strings.
+module StringUtils
+
+  # Converts the given query String to a Hash object.
+  # A query string is identified by a set of
+  # key-value pairs in the format "{key}={value}"
+  # separated by the '&' character.
+  #
+  # Arguments:
+  #   string: the string to convert
+  def self.query_string_to_hash(string)
+    dict = {}
+    string.split('&').map do |pair|
+      key, value = pair.split('=')
+      dict[key] = value.sub('+', ' ')
+    end
+    dict
+  end
+
+end
+
+class String
+
+  # Capitalizes every word of the given String.
+  def titleize
+    self.split('-').map(&:capitalize).join('-')
+  end
+
+end

data/lib/gyoza-languages/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GyozaLanguages
+  VERSION = '1.0.1'
+  # The content sent as the HTTP Server header
+  SERVER_NAME = "Gyoza-Languages/#{VERSION}"
+  DEFAULT_PORT = 9172
+
+  SPEC_NAME = $PROGRAM_NAME.split('/').last
+  SPEC_DESCRIPTION = 'A Ruby implementation of the Github linguist project with an integrated simple HTTP web server'
+  REPOSITORIES_DIRECTORY_ENV_NAME = 'REPOSITORIES_DIRECTORY'
+end

data/lib/gyoza-languages.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'gyoza-languages/version'
+
+module GyozaLanguages
+
+  require_relative 'gyoza-languages/gyoza_app'
+  require_relative 'gyoza-languages/gyoza_language_app'
+  require_relative 'gyoza-languages/gyoza_error'
+  require_relative 'gyoza-languages/string_utils'
+
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: gyoza-languages
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Fulminazzo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: erb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: github-linguist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 9.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 9.0.0
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.5.0
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.8
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.1
+description: This Gem acts as a bridge between a simple Rest API and the Github linguist
+  program, to allow for languages retrieval with easy and parameterized requests.
+email:
+- gyoza@fulminazzo.it
+executables:
+- gyoza-languages
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- bin/gyoza-languages
+- lib/gyoza-languages.rb
+- lib/gyoza-languages/gyoza_app.rb
+- lib/gyoza-languages/gyoza_error.rb
+- lib/gyoza-languages/gyoza_language_app.rb
+- lib/gyoza-languages/string_utils.rb
+- lib/gyoza-languages/version.rb
+homepage: https://git.fulminazzo.it
+licenses:
+-
+metadata:
+  homepage_uri: https://git.fulminazzo.it
+  source_code_uri: https://github.com/git-gyoza/gyoza-languages
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby implementation of the Github linguist project with an integrated simple
+  HTTP web server
+test_files: []