particle-calendar 0.1.0

data/lib/availability/busy_period.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Availability
+  BusyPeriod = Data.define(:starts_at, :ends_at) do
+    alias_method :initialize_data, :initialize
+
+    def initialize(starts_at:, ends_at:)
+      raise ArgumentError, 'busy period end must be after start' unless ends_at > starts_at
+
+      initialize_data(starts_at: starts_at.getutc.freeze, ends_at: ends_at.getutc.freeze)
+    end
+
+    def intersects?(starts_at, ends_at)
+      self.starts_at < ends_at && self.ends_at > starts_at
+    end
+
+    private :initialize_data
+  end
+
+  Slot = Data.define(:starts_at, :ends_at) do
+    alias_method :initialize_data, :initialize
+
+    def initialize(starts_at:, ends_at:)
+      raise ArgumentError, 'slot end must be after start' unless ends_at > starts_at
+
+      initialize_data(starts_at: starts_at.getutc.freeze, ends_at: ends_at.getutc.freeze)
+    end
+
+    private :initialize_data
+  end
+
+  DayAvailability = Data.define(:date, :slots) do
+    alias_method :initialize_data, :initialize
+
+    def initialize(date:, slots:)
+      initialize_data(date: date, slots: slots.dup.freeze)
+    end
+
+    private :initialize_data
+  end
+end

data/lib/availability/calendar_fetcher.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+require_relative 'calendar_url'
+
+module Availability
+  # Downloads private calendar feeds with bounded redirects, timeouts, and size.
+  class CalendarFetcher
+    MAX_REDIRECTS = 5
+    MAX_BYTES = 20 * 1024 * 1024
+
+    def initialize(open_timeout: 10, read_timeout: 30)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def fetch(url, label: 'Calendar', redirects_left: MAX_REDIRECTS)
+      uri = URI.parse(CalendarUrl.normalize(url))
+      validate_uri!(uri, label)
+      response, body = request(uri, label)
+      handle_response(response, body, uri, label, redirects_left)
+    rescue FetchError
+      raise
+    rescue URI::InvalidURIError
+      raise FetchError, "#{label} has an invalid URL"
+    rescue Timeout::Error, SocketError, SystemCallError, OpenSSL::SSL::SSLError => e
+      raise FetchError, "#{label} download failed (#{e.class})"
+    end
+
+    private
+
+    def handle_response(response, body, uri, label, redirects_left)
+      return body if response.is_a?(Net::HTTPSuccess)
+      return follow_redirect(response, uri, label, redirects_left) if response.is_a?(Net::HTTPRedirection)
+
+      raise FetchError, "#{label} download failed with HTTP #{response.code}"
+    end
+
+    def follow_redirect(response, uri, label, redirects_left)
+      raise FetchError, "#{label} returned too many redirects" if redirects_left.zero?
+
+      location = response['location']
+      raise FetchError, "#{label} returned a redirect without a location" if location.nil? || location.empty?
+
+      fetch(URI.join(uri, location).to_s, label: label, redirects_left: redirects_left - 1)
+    end
+
+    def validate_uri!(uri, label)
+      return if uri.is_a?(URI::HTTP) && uri.host && %w[http https].include?(uri.scheme)
+
+      raise FetchError, "#{label} has an invalid HTTP(S) URL"
+    end
+
+    def request(uri, label)
+      request = build_request(uri)
+      Net::HTTP.start(uri.host, uri.port, **connection_options(uri)) do |http|
+        read_response(http, request, label)
+      end
+    end
+
+    def build_request(uri)
+      Net::HTTP::Get.new(uri.request_uri).tap do |request|
+        request['User-Agent'] = 'availability-static-generator/1.0'
+        request['Accept'] = 'text/calendar, text/plain;q=0.9, */*;q=0.1'
+      end
+    end
+
+    def connection_options(uri)
+      {
+        use_ssl: uri.scheme == 'https',
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      }
+    end
+
+    def read_response(http, request, label)
+      result = nil
+      http.request(request) do |response|
+        body = stream_body(response, label) if response.is_a?(Net::HTTPSuccess)
+        result = [response, body]
+      end
+      result
+    end
+
+    def stream_body(response, label)
+      body = String.new(encoding: Encoding::BINARY)
+      response.read_body do |chunk|
+        if body.bytesize + chunk.bytesize > MAX_BYTES
+          raise FetchError, "#{label} response exceeded #{MAX_BYTES / 1_048_576} MB"
+        end
+
+        body << chunk
+      end
+      body
+    end
+  end
+end

data/lib/availability/calendar_parser.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'active_support/time'
+require 'icalendar'
+require 'icalendar/recurrence'
+require 'logger'
+
+require_relative 'event_timezone_validator'
+require_relative 'recurrence_expander'
+require_relative 'tolerant_icalendar_parser'
+
+module Availability
+  # Parses ICS events and expands occurrences into privacy-safe busy periods.
+  class CalendarParser
+    MAX_EVENTS_PER_CALENDAR = 10_000
+    NULL_LOGGER = Logger.new(IO::NULL)
+
+    attr_reader :ignored_event_count
+
+    def initialize(timezone:)
+      @timezone = timezone
+      @ignored_event_count = 0
+    end
+
+    def parse(ics, range_start:, range_end:, label: 'Calendar')
+      reset_diagnostics
+      with_silenced_dependency_logging { parse_periods(ics, range_start, range_end, label) }
+    rescue RecurrenceExpander::LimitError
+      raise ParseError, "#{label} exceeded the safe recurrence expansion limit"
+    rescue ParseError
+      raise
+    rescue StandardError => e
+      raise ParseError, "#{label} could not be parsed (#{e.class})"
+    end
+
+    private
+
+    def parse_periods(ics, range_start, range_end, label)
+      events = parse_events(ics, label)
+      valid_events = events.select { |event| valid_event?(event) }
+      @ignored_event_count += events.length - valid_events.length
+      override_keys = recurrence_override_keys(valid_events)
+      busy_periods(valid_events, override_keys, range_start, range_end)
+    end
+
+    def parse_events(ics, label)
+      calendars = parse_calendars(ics)
+      raise ParseError, "#{label} did not contain a calendar" if calendars.empty?
+
+      events = calendars.flat_map(&:events)
+      raise ParseError, "#{label} exceeded the safe event limit" if events.length > MAX_EVENTS_PER_CALENDAR
+
+      events
+    end
+
+    def parse_calendars(ics)
+      parse_with_tolerance(ics)
+    rescue ArgumentError
+      parse_with_tolerance(Icalendar::Parser.clean_bad_wrapping(ics))
+    end
+
+    def parse_with_tolerance(ics)
+      TolerantIcalendarParser.new(ics).tap do |parser|
+        parser.component_class = Icalendar::Calendar
+      end.parse
+    end
+
+    def valid_event?(event)
+      raise InvalidEventError, 'event contains an invalid property' if TolerantIcalendarParser.invalid_event?(event)
+
+      validate_event!(event)
+      value_to_utc(event.recurrence_id) if event.recurrence_id
+      true
+    rescue StandardError
+      false
+    end
+
+    def validate_event!(event)
+      EventTimezoneValidator.validate!(event)
+      return if cancelled?(event)
+
+      raise InvalidEventError, 'event is missing DTSTART' unless event.dtstart
+
+      return unless event.dtend || event.duration
+
+      starts_at = event.schedule.start_time
+      ends_at = event.schedule.end_time
+      raise InvalidEventError, 'event duration must be positive' unless ends_at > starts_at
+    end
+
+    def busy_periods(events, override_keys, range_start, range_end)
+      events.reject { |event| cancelled?(event) || implicit_instant?(event) }.flat_map do |event|
+        event_periods(event, override_keys, range_start, range_end)
+      end
+    end
+
+    def event_periods(event, override_keys, range_start, range_end)
+      occurrences(event, range_start, range_end).filter_map do |occurrence|
+        next if master_occurrence_overridden?(event, occurrence, override_keys)
+
+        period = occurrence_to_period(event, occurrence)
+        period if period&.intersects?(range_start, range_end)
+      end
+    rescue RecurrenceExpander::LimitError
+      raise
+    rescue StandardError
+      @ignored_event_count += 1
+      []
+    end
+
+    def occurrences(event, range_start, range_end)
+      return [] unless event.dtstart
+
+      @recurrence_expander.expand(event, range_start: range_start, range_end: range_end)
+    end
+
+    def occurrence_to_period(event, occurrence)
+      starts_at, ends_at = period_boundaries(event, occurrence)
+      raise InvalidEventError, 'event occurrence duration must be positive' unless ends_at > starts_at
+
+      BusyPeriod.new(starts_at, ends_at)
+    end
+
+    def period_boundaries(event, occurrence)
+      return all_day_boundaries(occurrence) if all_day?(event)
+      return floating_boundaries(occurrence) if floating?(event)
+
+      [occurrence.start_time.to_time.utc, occurrence.end_time.to_time.utc]
+    end
+
+    def all_day_boundaries(occurrence)
+      # DATE values are created in the process zone; recover their calendar date
+      # before placing the all-day span in the configured zone.
+      start_date = occurrence.start_time.getlocal.to_date
+      end_date = [occurrence.end_time.getlocal.to_date, start_date + 1].max
+      [local_midnight(start_date), local_midnight(end_date)]
+    end
+
+    def floating_boundaries(occurrence)
+      [floating_time_to_utc(occurrence.start_time), floating_time_to_utc(occurrence.end_time)]
+    end
+
+    def all_day?(event)
+      event.dtstart.is_a?(Icalendar::Values::Date)
+    end
+
+    def floating?(event)
+      event.dtstart.ical_params['tzid'].nil?
+    end
+
+    def implicit_instant?(event)
+      !all_day?(event) && !event.dtend && !event.duration
+    end
+
+    def floating_time_to_utc(time)
+      @timezone.local_time(time.year, time.month, time.day, time.hour, time.min, time.sec).utc
+    end
+
+    def local_midnight(date)
+      @timezone.local_time(date.year, date.month, date.day, 0, 0, 0).utc
+    end
+
+    def cancelled?(event)
+      event.status && event.status.to_s.casecmp('CANCELLED').zero?
+    end
+
+    def recurrence_override_keys(events)
+      events.each_with_object({}) do |event, keys|
+        next unless event.recurrence_id && event.uid
+
+        keys[[event.uid.to_s, value_to_utc(event.recurrence_id)]] = true
+      end
+    end
+
+    def master_occurrence_overridden?(event, occurrence, override_keys)
+      return false if event.recurrence_id || !event.uid
+
+      override_keys.key?([event.uid.to_s, occurrence.start_time.to_time.utc])
+    end
+
+    def value_to_utc(value)
+      Icalendar::Recurrence::TimeUtil.to_time(value).to_time.utc
+    end
+
+    def reset_diagnostics
+      @ignored_event_count = 0
+      @recurrence_expander = RecurrenceExpander.new
+    end
+
+    def with_silenced_dependency_logging
+      previous_logger = Icalendar.logger
+      Icalendar.logger = NULL_LOGGER
+      yield
+    ensure
+      Icalendar.logger = previous_logger
+    end
+  end
+end

data/lib/availability/calendar_url.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Availability
+  # Normalizes calendar subscription schemes into URLs Net::HTTP can fetch.
+  module CalendarUrl
+    module_function
+
+    def normalize(value)
+      value.sub(/\Awebcal:/i, 'https:')
+    end
+  end
+end

data/lib/availability/cli.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'securerandom'
+
+module Availability
+  # Command-line interface exposed by the installed particle executable.
+  class CLI
+    SUCCESS = 0
+    ERROR = 1
+    USAGE_ERROR = 2
+
+    def initialize(args:, output: $stdout, error: $stderr, env: ENV, working_directory: Dir.pwd,
+                   random_path: -> { SecureRandom.hex(12) })
+      @args = args.dup
+      @output = output
+      @error = error
+      @env = env
+      @working_directory = working_directory
+      @random_path = random_path
+    end
+
+    def run
+      dispatch(@args.shift)
+    rescue OptionParser::ParseError => e
+      @error.puts(e.message)
+      USAGE_ERROR
+    rescue Availability::Error => e
+      @error.puts(e.message)
+      ERROR
+    rescue StandardError => e
+      @error.puts("Particle failed unexpectedly (#{e.class}).")
+      ERROR
+    end
+
+    private
+
+    def dispatch(command)
+      return show_help if command.nil? || %w[help --help -h].include?(command)
+
+      case command
+      when 'generate' then generate
+      when 'setup' then setup
+      when 'version', '--version', '-v' then show_version
+      else
+        @error.puts("Unknown command: #{command}")
+        @error.puts(help)
+        USAGE_ERROR
+      end
+    end
+
+    def generate
+      options = generation_defaults
+      parser = generation_parser(options)
+      parser.parse!(@args)
+      return show_parser(parser) if options.delete(:help)
+
+      reject_arguments!(parser)
+      run_application(options)
+      SUCCESS
+    rescue Availability::Error => e
+      raise e.class, "Generation failed: #{e.message}"
+    end
+
+    def run_application(options)
+      Application.new(
+        config_path: options.fetch(:config),
+        output_dir: options.fetch(:output),
+        template_path: Assets.index_template_path,
+        favicon_path: Assets.favicon_path,
+        output: @output
+      ).run
+    end
+
+    def generation_defaults
+      {
+        config: @env.fetch('PARTICLE_CONFIG') do
+          @env.fetch('AVAILABILITY_CONFIG', File.join(@working_directory, 'particle.yml'))
+        end,
+        output: @env.fetch('PARTICLE_OUTPUT', File.join(@working_directory, 'public'))
+      }
+    end
+
+    def generation_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = 'Usage: particle generate [options]'
+        parser.on('-c', '--config PATH', 'Configuration file (or PARTICLE_CONFIG)') do |path|
+          options[:config] = path
+        end
+        parser.on('-o', '--output DIR', 'Static output directory (or PARTICLE_OUTPUT)') do |path|
+          options[:output] = path
+        end
+        parser.on('-h', '--help', 'Show this help') { options[:help] = true }
+      end
+    end
+
+    def setup
+      options = setup_defaults
+      parser = setup_parser(options)
+      parser.parse!(@args)
+      return show_parser(parser) if options.delete(:help)
+
+      reject_arguments!(parser)
+
+      setup = Setup.new(**options)
+      setup.run
+      print_setup_result(setup)
+      SUCCESS
+    end
+
+    def setup_defaults
+      {
+        config_path: File.join(@working_directory, 'particle.yml'),
+        nginx_path: File.join(@working_directory, 'particle.nginx.conf'),
+        output_dir: File.join(@working_directory, 'public'),
+        server_name: 'example.com',
+        url_path: "/#{@random_path.call}/"
+      }
+    end
+
+    def setup_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = 'Usage: particle setup [options]'
+        add_setup_path_options(parser, options)
+        add_setup_nginx_options(parser, options)
+        parser.on('-h', '--help', 'Show this help') { options[:help] = true }
+      end
+    end
+
+    def add_setup_path_options(parser, options)
+      parser.on('-c', '--config PATH', 'Sample configuration destination') { |path| options[:config_path] = path }
+      parser.on('-n', '--nginx PATH', 'Sample Nginx configuration destination') { |path| options[:nginx_path] = path }
+      parser.on('-o', '--output DIR', 'Generated static output directory') { |path| options[:output_dir] = path }
+    end
+
+    def add_setup_nginx_options(parser, options)
+      parser.on('--server-name NAME', 'Nginx server_name value') { |name| options[:server_name] = name }
+      parser.on('--url-path PATH', 'Private URL path, including leading/trailing slashes') do |path|
+        options[:url_path] = path
+      end
+    end
+
+    def reject_arguments!(parser)
+      return if @args.empty?
+
+      raise OptionParser::InvalidArgument, "Unexpected arguments: #{@args.join(' ')}\n#{parser}"
+    end
+
+    def print_setup_result(setup)
+      @output.puts("Created #{setup.config_path} (mode 0600)")
+      @output.puts("Created #{setup.nginx_path}")
+      @output.puts("Created output directory #{setup.output_dir}")
+      @output.puts('Next: edit the config, run particle generate, then review and install the Nginx file.')
+    end
+
+    def show_help
+      @output.puts(help)
+      SUCCESS
+    end
+
+    def show_parser(parser)
+      @output.puts(parser)
+      SUCCESS
+    end
+
+    def show_version
+      @output.puts("Particle #{VERSION}")
+      SUCCESS
+    end
+
+    def help
+      <<~HELP
+        Usage: particle COMMAND [options]
+
+        Commands:
+          setup       Create sample config and Nginx files
+          generate    Fetch calendars and generate static HTML
+          version     Print the installed version
+
+        Run `particle COMMAND --help` for command-specific options.
+      HELP
+    end
+  end
+end