Time

A simple web server that provides handy features surrounding time:

• Allows users to determine if their machine's clock is significantly off from the server's clock. This can be used to determine why TOTP codes generated by someone are invalid according to the server, which could be due to a significant time difference between the two clocks.
• Information about an IANA timezone, such as its abbreviation, if it currently observes daylight saving time, when the timezone started and when it will end, the UTC offset, and the difference in offsets between the timezone and the user's timezone.
• The week number according to the ISO 8601 standard.
• Shows a list of the ISO 3166-1 alpha-2 country codes.
• Sends the content in plain text when the User Agent indicates a command line tool such as curl.
• Shows information about the timezone of cities and countries.
• A world map showing the position of the sun and moon and where the sun is currently shining.
• Relative duration difference between two dates in different time zones.

Deployment

You only need to have a recent version of Go and have Make installed and understand the caveats section to deploy this project.

First clone the repository.

$ git clone https://codeberg.org/Gusted/time.git
$ cd time

Then build the project with Make.

$ make

You can cross compile the project by setting the GOARCH and GOOS environments.

$ GOARCH=arm64 GOOS=linux make

This results in a binary named time that upon executing will start the server.

The host and port to be used to serve the http server can be configured by passing -host <hostname> and -port <port> respectively when executing the binary.

Technical details

A high-level overview of that the code does and how it allows users to determine the offset between their machine and the server.

When a user visits the server, the javascript code will make a request to the server, and before doing so, it stores the current time. The server sends their current time back. Upon receiving the response from the server, it will store the current time. It will then compute \theta (the time difference between the clocks of the user and server) and \delta (the delay added by the round-trip, which can be seen as the accuracy) according to the following formula:

\theta = \frac{(t_{server}-t_{start})+(t_{server}-t_{end})}{2}\\[1em]
\delta = t_{start}-t_{end}

Where:

• t_{start} is the timestamp before sending the request.
• t_{server} is the timestamp sent by the server.
• t_{end} is the timetamp after receiving the response.

This is a simpler variation of the formula that's being used by the Network Time Protocol, where we neglect the time between processing the request and sending a response on the server.

Caveats

The expectation of the code is that the server that hosts this code has been correctly configured to have their time be in sync with an NTP. This means that no modification was made manually to the time in order to adjust for timezones or whatever. For specific details of how the code gets the system's time, we refer to Go's time documentation. It's advised to read the documentation provided by your operating system, or for Linux users, consulting the Arch Linux guide, to ensure proper time synchronization usage on the system this code is deployed.

The code relies on Go's time.LoadLocation function to get the necessary information about timezones. Your operating system may not have these zoneinfo files or only has a limited amount of them, in that case you should build this project with TAGS=timetzdata make, which will include a copy of the timezone files that's distributed by your Go version and will be used by time.LoadLocation if it cannot find the timzone in your operating system provided zoneinfo files.

The code relies on data from GeoNames to map country names to their capital city, such that `United Kingdom' will yield 'London' and map city names to the used timezone. GeoNames's data is based on official sources but can also be modified by volunteers; therefore, it may contain inaccurate information that can be propagated to this project, such as that an incorrect timezone is listed for a city. For performance and memory reasons, currently only cities that have been recorded to have a population of more than 15,000 people are used. The dataset contains alternate names for cities; for example, the city of Geneva in Switzerland is listed under its French name Genève and has Geneva as an alternate name. The alternate names also contain translations of the city's name and the IATA code of a major airport in that city. However, it's currently impractical to add the mapping of these names to the city's information due to the high number of conflicts.

License

The code is licensed under the MIT License. This project contains CSS from the Pico CSS project, which is licensed under the MIT License. This project uses certain files from The Time Zone Database, these files are released into the public domain. This project uses certain files from the GeoNames geographical database, these files are licensed under the CC BY 4.0.