particle-calendar 0.1.0

data/lib/availability/config.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'uri'
+require 'yaml'
+require 'tzinfo'
+
+require_relative 'calendar_url'
+require_relative 'config_value_parser'
+
+module Availability
+  # Loads, normalizes, and validates generator configuration.
+  class Config
+    include ConfigValueParser
+
+    TOP_LEVEL_KEYS = %w[
+      enabled timezone calendar_urls days_to_show minimum_slot_minutes event_buffer availability
+    ].freeze
+    EVENT_BUFFER_KEYS = %w[before_minutes after_minutes].freeze
+    WEEKDAYS = %w[sunday monday tuesday wednesday thursday friday saturday].freeze
+    ENV_REFERENCE = /\A\$\{([A-Z][A-Z0-9_]*)\}\z/
+    TIME_FORMAT = /\A(?:[01]\d|2[0-3]):[0-5]\d\z/
+    MAX_DAYS_TO_SHOW = 366
+    MAX_CALENDAR_URLS = 20
+
+    attr_reader :enabled, :timezone, :calendar_urls, :days_to_show,
+                :minimum_slot_minutes, :buffer_before_minutes, :buffer_after_minutes
+
+    def self.load(path, env: ENV)
+      raise ConfigError, "configuration file not found: #{path}" unless File.file?(path)
+
+      raw = YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: false)
+      raise ConfigError, 'configuration root must be a mapping' unless raw.is_a?(Hash)
+
+      new(raw, env: env)
+    rescue Psych::Exception => e
+      raise ConfigError, "invalid YAML in #{path}: #{e.message.lines.first.strip}"
+    end
+
+    def initialize(raw, env: ENV)
+      @raw = stringify_keys(raw)
+      @env = env
+      validate_known_keys(@raw, TOP_LEVEL_KEYS, 'configuration')
+      @enabled = boolean('enabled', default: true)
+      @timezone = parse_timezone
+      @days_to_show = bounded_positive_integer('days_to_show', default: 28, maximum: MAX_DAYS_TO_SHOW)
+      @minimum_slot_minutes = nonnegative_integer('minimum_slot_minutes', default: 0)
+      parse_buffers
+      @availability = parse_availability
+      @calendar_urls = parse_calendar_urls
+    end
+
+    def windows_for(date)
+      @availability.fetch(WEEKDAYS.fetch(date.wday), @availability.fetch('default'))
+    end
+
+    private
+
+    def stringify_keys(value)
+      if value.is_a?(Hash)
+        return value.each_with_object({}) do |(key, item), hash|
+          hash[key.to_s] = stringify_keys(item)
+        end
+      end
+      return value.map { |item| stringify_keys(item) } if value.is_a?(Array)
+
+      value
+    end
+
+    def parse_timezone
+      name = @raw.fetch('timezone', 'Europe/Berlin')
+      raise ConfigError, 'timezone must be a string' unless name.is_a?(String)
+
+      TZInfo::Timezone.get(name)
+    rescue TZInfo::InvalidTimezoneIdentifier
+      raise ConfigError, "timezone is unknown: #{name}"
+    end
+
+    def parse_buffers
+      buffer = @raw.fetch('event_buffer', {})
+      raise ConfigError, 'event_buffer must be a mapping' unless buffer.is_a?(Hash)
+
+      validate_known_keys(buffer, EVENT_BUFFER_KEYS, 'event_buffer')
+      @buffer_before_minutes = nested_nonnegative_integer(buffer, 'before_minutes', 0, 'event_buffer.before_minutes')
+      @buffer_after_minutes = nested_nonnegative_integer(buffer, 'after_minutes', 0, 'event_buffer.after_minutes')
+    end
+
+    def parse_calendar_urls
+      # Disabled mode must not depend on feed secrets being present.
+      return [].freeze unless enabled
+
+      urls = @raw.fetch('calendar_urls', [])
+      raise ConfigError, 'calendar_urls must be an array' unless urls.is_a?(Array)
+      if urls.length > MAX_CALENDAR_URLS
+        raise ConfigError, "calendar_urls must contain at most #{MAX_CALENDAR_URLS} URLs"
+      end
+
+      resolved = urls.each_with_index.map { |value, index| parse_calendar_url(value, index) }
+      raise ConfigError, 'calendar_urls must contain at least one URL when enabled' if resolved.empty?
+
+      resolved.freeze
+    end
+
+    def parse_calendar_url(value, index)
+      label = "calendar_urls[#{index}]"
+      raise ConfigError, "#{label} must be a non-empty string" unless value.is_a?(String) && !value.strip.empty?
+
+      match = ENV_REFERENCE.match(value.strip)
+      value = resolve_environment(match[1], label) if match
+      validate_url(value, label)
+    end
+
+    def resolve_environment(name, label)
+      value = @env[name]
+      raise ConfigError, "#{label} references missing environment variable #{name}" if value.nil? || value.empty?
+
+      value
+    end
+
+    def validate_url(value, label)
+      normalized = CalendarUrl.normalize(value)
+      uri = URI.parse(normalized)
+      unless uri.is_a?(URI::HTTP) && uri.host && %w[http https].include?(uri.scheme)
+        raise ConfigError, "#{label} must be an HTTP(S) or webcal URL"
+      end
+
+      normalized
+    rescue URI::InvalidURIError
+      raise ConfigError, "#{label} must be a valid HTTP(S) or webcal URL"
+    end
+
+    def parse_availability
+      source = @raw['availability']
+      raise ConfigError, 'availability must be a mapping' unless source.is_a?(Hash)
+
+      unknown = source.keys - (['default'] + WEEKDAYS)
+      raise ConfigError, "availability has unknown key: #{unknown.first}" unless unknown.empty?
+      raise ConfigError, 'availability.default is required' unless source.key?('default')
+
+      source.each_with_object({}) do |(day, definition), result|
+        result[day] = parse_day_definition(definition, "availability.#{day}")
+      end.freeze
+    end
+
+    def parse_day_definition(definition, key)
+      return unavailable_day(definition, key) if unavailable?(definition)
+
+      windows = definition.is_a?(Array) ? definition : [definition]
+      raise ConfigError, "#{key} must contain at least one window or unavailable: true" if windows.empty?
+
+      parsed = windows.each_with_index.map { |window, index| parse_window(window, "#{key}[#{index}]") }
+      parsed.sort_by!(&:first)
+      validate_nonoverlapping_windows(parsed, key)
+      parsed.freeze
+    end
+
+    def unavailable?(definition)
+      definition.is_a?(Hash) && definition['unavailable'] == true
+    end
+
+    def unavailable_day(definition, key)
+      extra = definition.keys - ['unavailable']
+      raise ConfigError, "#{key} cannot combine unavailable with windows" unless extra.empty?
+
+      [].freeze
+    end
+
+    def validate_nonoverlapping_windows(windows, key)
+      windows.each_cons(2) do |left, right|
+        raise ConfigError, "#{key} windows must not overlap" if left.last > right.first
+      end
+    end
+
+    def parse_window(window, key)
+      raise ConfigError, "#{key} must be a start/end mapping" unless window.is_a?(Hash)
+
+      unknown = window.keys - %w[start end]
+      raise ConfigError, "#{key} has unknown key: #{unknown.first}" unless unknown.empty?
+
+      starts = parse_time(window['start'], "#{key}.start")
+      ends = parse_time(window['end'], "#{key}.end", end_of_day: true)
+      raise ConfigError, "#{key}.start must be earlier than #{key}.end" unless starts < ends
+
+      [starts, ends].freeze
+    end
+
+    def parse_time(value, key, end_of_day: false)
+      raise ConfigError, "#{key} must use HH:MM (24-hour time)" unless value.is_a?(String) && TIME_FORMAT.match?(value)
+      return 24 * 60 if end_of_day && value == '00:00'
+
+      hour, minute = value.split(':').map(&:to_i)
+      (hour * 60) + minute
+    end
+  end
+end

data/lib/availability/config_value_parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Availability
+  # Shared scalar and schema validation helpers for configuration loading.
+  module ConfigValueParser
+    private
+
+    def validate_known_keys(hash, allowed, label)
+      unknown = hash.keys - allowed
+      raise ConfigError, "#{label} has unknown key: #{unknown.first}" unless unknown.empty?
+    end
+
+    def boolean(key, default:)
+      value = @raw.fetch(key, default)
+      return value if [true, false].include?(value)
+
+      raise ConfigError, "#{key} must be true or false"
+    end
+
+    def positive_integer(key, default:)
+      value = @raw.fetch(key, default)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ConfigError, "#{key} must be a positive integer"
+    end
+
+    def bounded_positive_integer(key, default:, maximum:)
+      value = positive_integer(key, default: default)
+      return value if value <= maximum
+
+      raise ConfigError, "#{key} must be at most #{maximum}"
+    end
+
+    def nonnegative_integer(key, default:)
+      value = @raw.fetch(key, default)
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise ConfigError, "#{key} must be a non-negative integer"
+    end
+
+    def nested_nonnegative_integer(hash, key, default, label)
+      value = hash.fetch(key, default)
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise ConfigError, "#{label} must be a non-negative integer"
+    end
+  end
+end

data/lib/availability/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Availability
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class FetchError < Error; end
+  class ParseError < Error; end
+  class InvalidEventError < Error; end
+  class SetupError < Error; end
+end

data/lib/availability/event_timezone_validator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'active_support/time'
+require 'icalendar'
+
+module Availability
+  # Rejects TZID values the iCalendar parser could not resolve safely.
+  class EventTimezoneValidator
+    def self.validate!(event)
+      new(event).validate!
+    end
+
+    def initialize(event)
+      @event = event
+    end
+
+    def validate!
+      temporal_values.each do |value|
+        raise InvalidEventError, 'event contains an unresolved timezone' if unresolved_timezone?(value)
+      end
+    end
+
+    private
+
+    def temporal_values
+      values = [@event.dtstart, @event.dtend, @event.recurrence_id, @event.exdate, @event.rdate]
+      values.flat_map { |value| flatten_temporal_value(value) }.compact
+    end
+
+    def flatten_temporal_value(value)
+      return [] if value.nil?
+      return value.flat_map { |item| flatten_temporal_value(item) } if value.is_a?(Array)
+      if value.is_a?(Icalendar::Values::Helpers::Array)
+        return value.value.flat_map { |item| flatten_temporal_value(item) }
+      end
+
+      [value]
+    end
+
+    def unresolved_timezone?(value)
+      return false unless value.respond_to?(:ical_params)
+
+      tzid = Array(value.ical_params['tzid']).first
+      return false if tzid.nil? || tzid == 'UTC'
+      return false if resolved_time_value?(value.value)
+
+      timezone_store = value.respond_to?(:timezone_store) && value.timezone_store
+      timezone_store.nil? || timezone_store.retrieve(tzid).nil?
+    end
+
+    def resolved_time_value?(value)
+      value.is_a?(Time) || value.is_a?(ActiveSupport::TimeWithZone)
+    end
+  end
+end

data/lib/availability/recurrence_expander.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Availability
+  # Expands recurrences in bounded chunks and enforces occurrence-count limits.
+  class RecurrenceExpander
+    MAX_OCCURRENCES_PER_EVENT = 10_000
+    MAX_OCCURRENCES_PER_CALENDAR = 50_000
+    SECONDLY_CHUNK_SECONDS = 60 * 60
+    MINUTELY_CHUNK_SECONDS = 24 * 60 * 60
+
+    class LimitError < StandardError; end
+
+    def initialize
+      @calendar_occurrence_count = 0
+    end
+
+    def expand(event, range_start:, range_end:)
+      occurrences = {}
+      cursor = range_start
+      chunk_seconds = expansion_chunk_seconds(event, range_start, range_end)
+
+      while cursor < range_end
+        chunk_end = [cursor + chunk_seconds, range_end].min
+        add_occurrences(occurrences, event, cursor, chunk_end)
+        cursor = chunk_end
+      end
+
+      occurrences.values
+    end
+
+    private
+
+    def add_occurrences(occurrences, event, range_start, range_end)
+      event.occurrences_between(range_start, range_end, spans: true).each do |occurrence|
+        key = occurrence_key(occurrence)
+        next if occurrences.key?(key)
+
+        track_occurrence!(occurrences.length + 1)
+        occurrences[key] = occurrence
+      end
+    end
+
+    def expansion_chunk_seconds(event, range_start, range_end)
+      frequencies = event.rrule.map { |rule| rule.value_ical[/FREQ=([^;]+)/, 1] }
+      return SECONDLY_CHUNK_SECONDS if frequencies.include?('SECONDLY')
+      return MINUTELY_CHUNK_SECONDS if frequencies.include?('MINUTELY')
+
+      range_end - range_start
+    end
+
+    def occurrence_key(occurrence)
+      [occurrence.start_time.to_time.utc, occurrence.end_time.to_time.utc]
+    end
+
+    def track_occurrence!(event_count)
+      @calendar_occurrence_count += 1
+      return if within_limits?(event_count)
+
+      raise LimitError
+    end
+
+    def within_limits?(event_count)
+      event_count <= MAX_OCCURRENCES_PER_EVENT && @calendar_occurrence_count <= MAX_OCCURRENCES_PER_CALENDAR
+    end
+  end
+end

data/lib/availability/renderer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'erb'
+
+module Availability
+  # Renders calculated availability into a self-contained static HTML page.
+  class Renderer
+    ROBOTS = "User-agent: *\nDisallow: /\n"
+
+    def initialize(template_path:)
+      @template = ERB.new(File.read(template_path), trim_mode: '-')
+    end
+
+    def render(days:, generated_at:, timezone:, enabled:, today:, days_to_show:)
+      view = View.new(
+        days: days,
+        generated_at: generated_at,
+        timezone: timezone,
+        enabled: enabled,
+        today: today,
+        days_to_show: days_to_show
+      )
+      @template.result(view.template_binding)
+    end
+
+    # Exposes only display-safe availability values and formatting helpers to ERB.
+    class View
+      WEEKDAYS = %w[monday tuesday wednesday thursday friday saturday sunday].freeze
+
+      attr_reader :enabled, :today
+
+      def initialize(days:, generated_at:, timezone:, enabled:, today:, days_to_show:)
+        @days = days
+        @generated_at = generated_at
+        @timezone = timezone
+        @enabled = enabled
+        @today = today
+        @days_to_show = days_to_show
+      end
+
+      def template_binding
+        binding
+      end
+
+      def h(value)
+        CGI.escapeHTML(value.to_s)
+      end
+
+      def format_date(date)
+        "#{date.strftime('%A')}, #{date.day} #{date.strftime('%B %Y')}"
+      end
+
+      def format_compact_date(date)
+        date.strftime('%a %-d %b')
+      end
+
+      def format_week_label(week)
+        first_date = week.compact.first.date
+        monday = first_date - (first_date.cwday - 1)
+        "Week of #{monday.day} #{monday.strftime('%B %Y')}"
+      end
+
+      def format_time(time)
+        @timezone.to_local(time.getutc).strftime('%H:%M')
+      end
+
+      def weeks
+        return [] if @days.empty?
+
+        padded_days = Array.new(@days.first.date.cwday - 1) + @days
+        padded_days.concat(Array.new((7 - padded_days.length) % 7))
+        padded_days.each_slice(7).to_a
+      end
+
+      def weekdays
+        WEEKDAYS
+      end
+
+      def updated_at
+        @timezone.to_local(@generated_at.getutc).strftime('%-d %b %Y, %H:%M %Z')
+      end
+
+      def timezone_name
+        @timezone.identifier
+      end
+
+      def period_description
+        final_date = @today + @days_to_show - 1
+        return @today.strftime('%-d %b %Y') if final_date == @today
+
+        start_with_year = @today.strftime('%-d %b %Y')
+        final_with_year = final_date.strftime('%-d %b %Y')
+        return "#{start_with_year}–#{final_with_year}" if @today.year != final_date.year
+
+        return "#{@today.day}–#{final_with_year}" if @today.month == final_date.month
+
+        "#{@today.strftime('%-d %b')}–#{final_with_year}"
+      end
+    end
+  end
+end

data/lib/availability/setup.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+
+module Availability
+  # Creates deployment starter files without replacing existing configuration.
+  class Setup
+    SERVER_NAME_PATTERN = /\A[a-zA-Z0-9.-]+\z/
+    URL_PATH_PATTERN = %r{\A/[a-zA-Z0-9_-]+/\z}
+
+    def initialize(config_path:, nginx_path:, output_dir:, server_name:, url_path:)
+      @config_path = File.expand_path(config_path)
+      @nginx_path = File.expand_path(nginx_path)
+      @output_dir = File.expand_path(output_dir)
+      @server_name = server_name
+      @url_path = url_path
+    end
+
+    attr_reader :config_path, :nginx_path, :output_dir
+
+    def run
+      validate!
+      ensure_targets_are_available!
+      create_files
+      FileUtils.mkdir_p(output_dir)
+      true
+    rescue SystemCallError => e
+      cleanup_created_files
+      raise SetupError, "Setup failed: #{e.message}"
+    end
+
+    private
+
+    def validate!
+      raise SetupError, 'Config and Nginx paths must be different' if config_path == nginx_path
+      raise SetupError, 'Output directory path must not contain newlines' if output_dir.match?(/[\r\n]/)
+      raise SetupError, 'Server name must contain only letters, numbers, dots, and hyphens' unless valid_server_name?
+      raise SetupError, 'URL path must look like /private-path/' unless @url_path.match?(URL_PATH_PATTERN)
+    end
+
+    def valid_server_name?
+      !@server_name.empty? && @server_name.match?(SERVER_NAME_PATTERN)
+    end
+
+    def ensure_targets_are_available!
+      existing = [config_path, nginx_path].select { |path| File.exist?(path) || File.symlink?(path) }
+      return if existing.empty?
+
+      raise SetupError, "Refusing to overwrite existing file: #{existing.first}"
+    end
+
+    def create_files
+      @created_files = []
+      write_exclusive(config_path, File.binread(Assets.example_config_path), 0o600)
+      write_exclusive(nginx_path, rendered_nginx, 0o644)
+    end
+
+    def write_exclusive(path, contents, mode)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, File::WRONLY | File::CREAT | File::EXCL, mode) { |file| file.write(contents) }
+      @created_files << path
+      File.chmod(mode, path)
+    end
+
+    def rendered_nginx
+      template = ERB.new(File.read(Assets.nginx_template_path), trim_mode: '-')
+      template.result(binding)
+    end
+
+    def escaped_output_dir
+      output_dir.gsub('\\', '\\\\').gsub('"', '\\"')
+    end
+
+    def cleanup_created_files
+      @created_files&.each { |path| File.unlink(path) if File.file?(path) }
+    end
+  end
+end

data/lib/availability/tolerant_icalendar_parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'icalendar'
+
+module Availability
+  # Isolates property-level iCalendar failures to the VEVENT that contains them.
+  class TolerantIcalendarParser < Icalendar::Parser
+    INVALID_MARKER = :@availability_invalid_event
+    SUPPORTED_VALUE_TYPES = %w[
+      BINARY BOOLEAN CAL-ADDRESS DATE DATE-TIME DURATION FLOAT INTEGER PERIOD RECUR TEXT TIME URI UTC-OFFSET
+    ].freeze
+
+    def self.invalid_event?(event)
+      event.instance_variable_defined?(INVALID_MARKER)
+    end
+
+    private
+
+    def parse_property(component, fields = nil)
+      if component.is_a?(Icalendar::Event) && unsupported_value_type?(fields)
+        mark_invalid(component)
+        return
+      end
+
+      super
+    rescue StandardError
+      raise unless component.is_a?(Icalendar::Event)
+
+      mark_invalid(component)
+    end
+
+    def parse_component(component)
+      super
+    rescue StandardError
+      raise unless component.is_a?(Icalendar::Event)
+
+      mark_invalid(component)
+      discard_remaining_event
+      component
+    end
+
+    def mark_invalid(event)
+      event.instance_variable_set(INVALID_MARKER, true)
+    end
+
+    def unsupported_value_type?(fields)
+      value_type = fields&.dig(:params, 'value')&.first
+      value_type && !SUPPORTED_VALUE_TYPES.include?(value_type.upcase)
+    end
+
+    def discard_remaining_event
+      loop do
+        fields = next_fields
+        return if fields.nil? || event_end?(fields)
+      rescue StandardError
+        next
+      end
+    end
+
+    def event_end?(fields)
+      fields[:name] == 'end' && fields[:value].casecmp('VEVENT').zero?
+    end
+  end
+end

data/lib/availability/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Availability
+  VERSION = '0.1.0'
+end

data/lib/availability.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'availability/version'
+require_relative 'availability/assets'
+require_relative 'availability/errors'
+require_relative 'availability/calendar_url'
+require_relative 'availability/config_value_parser'
+require_relative 'availability/config'
+require_relative 'availability/calendar_fetcher'
+require_relative 'availability/busy_period'
+require_relative 'availability/tolerant_icalendar_parser'
+require_relative 'availability/event_timezone_validator'
+require_relative 'availability/recurrence_expander'
+require_relative 'availability/calendar_parser'
+require_relative 'availability/availability_calculator'
+require_relative 'availability/renderer'
+require_relative 'availability/atomic_writer'
+require_relative 'availability/application'
+require_relative 'availability/setup'
+require_relative 'availability/cli'