📅 Calendar Service

A self-hosted, high-performance calendar service written in Go. It provides both gRPC and RESTful JSON APIs to check for holidays, days off, and workdays based on customizable country-specific calendars.

This service is designed to be run by you, giving you full control over your data and infrastructure.

✨ Features

• 🏡 Self-Hosted: Full control over your data and deployment.
• 🔄 Dual API: Native support for both gRPC and a RESTful JSON gateway.
• 🗓️ Holiday & Workday Calculation:
  • Check if a specific date is a day off.
  • Check multiple dates at once.
  • Find the date of the previous working day.
• 🗂️ Customizable Calendars: Load calendar data from local files (e.g., JSON, XML).
• ⚡ High Performance: Built with Go for speed and efficiency.

🔌 API

The service exposes its functionality through a simple and clear API.

gRPC

The primary API is defined using protobuf in api/calendar/calendar.proto.

Services & Methods:

• Calendar.IsDayOff: Checks if a given date is a non-working day.
• Calendar.IsDaysOff: Checks a list of dates to see if they are non-working days.
• Calendar.PreviousWorkDay: Finds the last working day before a specified date.

REST Gateway

A RESTful JSON API is also available, which mirrors the gRPC functionality.

Endpoints:

• GET /v1/is_day_off?country=<COUNTRY_CODE>&date=<YYYY-MM-DD>
• GET /v1/is_days_off?country=<COUNTRY_CODE>&dates=<YYYY-MM-DD>&dates=<...>
• GET /v1/previous_work_day?country=<COUNTRY_CODE>&date=<YYYY-MM-DD>&count=<DAYS>

An OpenAPI v2 specification is available in docs/apidocs.swagger.json.

🚀 Getting Started

Prerequisites

• Go (version 1.21 or newer recommended)
• make

Installation & Running

1. Clone the repository:

   git clone <repository-url>

2. Install dependencies: This command will install golangci-lint and all necessary protoc plugins into the local ./bin directory.

   make install-deps

3. Generate API code: If you make changes to the .proto files, you must regenerate the Go code.

   make generate

4. Run the service: The easiest way to run the server is using the run target, which uses the example configuration.

   make run

   By default, the service will be available at localhost:8080 (for REST) and localhost:8082 (for gRPC).

⚙️ Configuration

The service is configured via a YAML file. An example can be found at examples/config.yml.

You can specify a different configuration file by setting the CONFIG_FILE_PATH environment variable:

CONFIG_FILE_PATH=/path/to/your/config.yml go run cmd/main.go

🧑‍💻 Development

Linting

To check the code against the project's linting rules:

make lint

Tidy Go Modules

make tidy