diff --git a/lib/plausible/sites.ex b/lib/plausible/sites.ex index b41591e3f..eca534e70 100644 --- a/lib/plausible/sites.ex +++ b/lib/plausible/sites.ex @@ -206,25 +206,23 @@ defmodule Plausible.Sites do @doc """ Returns the date of the first recorded stat in the timezone configured by the user. - This function does 2 transformations: - UTC %NaiveDateTime{} -> Local %DateTime{} -> Local %Date + This function does 3 transformations: + Date -> UTC DateTime at 00:00 -> Local %DateTime{} -> Local %Date ## Examples - iex> Plausible.Site.local_start_date(%Plausible.Site{stats_start_date: nil}) + iex> %Plausible.Site{stats_start_date: nil} = site = Plausible.Factory.insert(:site) + iex> Plausible.Sites.local_start_date(site) nil - iex> utc_start = ~N[2022-09-28 00:00:00] - iex> tz = "Europe/Helsinki" - iex> site = %Plausible.Site{stats_start_date: utc_start, timezone: tz} - iex> Plausible.Site.local_start_date(site) + iex> site = %Plausible.Site{stats_start_date: ~D[2022-09-28], timezone: "Europe/Helsinki"} + iex> Plausible.Sites.local_start_date(site) ~D[2022-09-28] - iex> utc_start = ~N[2022-09-28 00:00:00] - iex> tz = "America/Los_Angeles" - iex> site = %Plausible.Site{stats_start_date: utc_start, timezone: tz} - iex> Plausible.Site.local_start_date(site) + iex> site = %Plausible.Site{stats_start_date: ~D[2022-09-28], timezone: "America/Los_Angeles"} + iex> Plausible.Sites.local_start_date(site) ~D[2022-09-27] + """ @spec local_start_date(Site.t()) :: Date.t() | nil def local_start_date(site) do diff --git a/lib/plausible/timezones.ex b/lib/plausible/timezones.ex index 9aa030e3d..b78f7fb43 100644 --- a/lib/plausible/timezones.ex +++ b/lib/plausible/timezones.ex @@ -6,29 +6,130 @@ defmodule Plausible.Timezones do |> Enum.sort_by(& &1[:offset], :desc) end - @spec to_utc_datetime(NaiveDateTime.t(), String.t()) :: DateTime.t() - def to_utc_datetime(naive_date_time, timezone) do - case Timex.to_datetime(naive_date_time, timezone) do - %DateTime{} = tz_dt -> - Timex.Timezone.convert(tz_dt, "UTC") + @doc """ + Represents wall time as Etc/UTC. - %Timex.AmbiguousDateTime{after: after_dt} -> - Timex.Timezone.convert(after_dt, "UTC") + iex> to_utc_datetime(~N[2024-03-16 09:50:45], "Asia/Kuala_Lumpur") + ~U[2024-03-16 01:50:45Z] - {:error, {:could_not_resolve_timezone, _, _, _}} -> - Timex.Timezone.convert(naive_date_time, "UTC") + When wall time is ambiguous - for instance during changing from summer to winter time - + the larger Etc/UTC timestamp is returned by default. + + # before the CEST -> CET overlap + iex> to_utc_datetime(~N[2018-10-28 01:59:59], "Europe/Copenhagen") + ~U[2018-10-27 23:59:59Z] + + # during + iex> to_utc_datetime(~N[2018-10-28 02:00:00], "Europe/Copenhagen") + ~U[2018-10-28 01:00:00Z] + + iex> to_utc_datetime(~N[2018-10-28 02:00:00], "Europe/Copenhagen", :up) + ~U[2018-10-28 01:00:00Z] + + iex> to_utc_datetime(~N[2018-10-28 02:00:00], "Europe/Copenhagen", :down) + ~U[2018-10-28 00:00:00Z] + + iex> to_utc_datetime(~N[2018-10-28 02:30:00], "Europe/Copenhagen") + ~U[2018-10-28 01:30:00Z] + + # after + iex> to_utc_datetime(~N[2018-10-28 03:00:00], "Europe/Copenhagen") + ~U[2018-10-28 02:00:00Z] + + When there is a gap in wall time - for instance in spring when the clocks are turned forward - + the larger Etc/UTC timestamp (at the end of the gap) is returned by default as well. + + # before the CET -> CEST gap + iex> to_utc_datetime(~N[2019-03-31 01:59:59], "Europe/Copenhagen") + ~U[2019-03-31 00:59:59Z] + + # during + iex> to_utc_datetime(~N[2019-03-31 02:00:00], "Europe/Copenhagen") + ~U[2019-03-31 01:00:00Z] + + iex> to_utc_datetime(~N[2019-03-31 02:30:00], "Europe/Copenhagen", :up) + ~U[2019-03-31 01:00:00Z] + + iex> to_utc_datetime(~N[2019-03-31 02:30:00], "Europe/Copenhagen", :down) + ~U[2019-03-31 00:59:59.999999Z] + + # after + iex> to_utc_datetime(~N[2019-03-31 03:00:00], "Europe/Copenhagen") + ~U[2019-03-31 01:00:00Z] + + If the supplied time zone is invalid, the wall time is assumed to be Etc/UTC. + + iex> to_utc_datetime(~N[2024-03-16 09:50:45], "Europe/Asia") + ~U[2024-03-16 09:50:45Z] + + """ + @spec to_utc_datetime(NaiveDateTime.t(), String.t(), :up | :down) :: DateTime.t() + def to_utc_datetime(naive_date_time, timezone, direction \\ :up) do + case DateTime.from_naive(naive_date_time, timezone) do + {:ok, date_time} -> + DateTime.shift_zone!(date_time, "Etc/UTC") + + {:gap, before_dt, after_dt} -> + DateTime.shift_zone!(pick_datetime(direction, before_dt, after_dt), "Etc/UTC") + + {:ambiguous, first_dt, second_dt} -> + DateTime.shift_zone!(pick_datetime(direction, first_dt, second_dt), "Etc/UTC") + + {:error, :time_zone_not_found} -> + DateTime.from_naive!(naive_date_time, "Etc/UTC") end end - @spec to_date_in_timezone(Date.t() | NaiveDateTime.t() | DateTime.t(), String.t()) :: Date.t() + defp pick_datetime(:up, _, dt), do: dt + defp pick_datetime(:down, dt, _), do: dt + + @doc """ + Same as `to_datetime_in_timezone/2` but extracts the date from the result. + + iex> to_date_in_timezone(~N[2024-03-16 01:50:45], "Asia/Kuala_Lumpur") + ~D[2024-03-16] + + """ + @spec to_date_in_timezone(NaiveDateTime.t() | DateTime.t() | Date.t(), String.t()) :: Date.t() def to_date_in_timezone(dt, timezone) do - to_datetime_in_timezone(dt, timezone) |> Timex.to_date() + dt |> to_datetime_in_timezone(timezone) |> DateTime.to_date() end - @spec to_datetime_in_timezone(Date.t() | NaiveDateTime.t() | DateTime.t(), String.t()) :: + @doc """ + Represents a timestamp in a different timezone. + Naive datetimes are assumed to be in Etc/UTC timezone. + Dates are assumed to mean a Etc/UTC midnight. + + iex> to_datetime_in_timezone(~N[2024-03-16 01:50:45], "Asia/Kuala_Lumpur") + #DateTime<2024-03-16 09:50:45+08:00 +08 Asia/Kuala_Lumpur> + + # see https://stackoverflow.com/questions/53076575/time-zones-etc-gmt-why-it-is-other-way-round + iex> to_datetime_in_timezone(~N[2024-03-16 01:50:45], "Etc/GMT-8") + #DateTime<2024-03-16 09:50:45+08:00 +08 Etc/GMT-8> + + iex> to_datetime_in_timezone(~N[2024-03-16 01:50:45], "GMT+8") + #DateTime<2024-03-16 09:50:45+08:00 +08 GMT+8> + + iex> to_datetime_in_timezone(~D[2018-10-28], "Europe/Copenhagen") + #DateTime<2018-10-28 02:00:00+02:00 CEST Europe/Copenhagen> + + """ + @spec to_datetime_in_timezone(NaiveDateTime.t() | DateTime.t() | Date.t(), String.t()) :: DateTime.t() - def to_datetime_in_timezone(dt, timezone) do - dt |> Timex.to_datetime("UTC") |> Timex.Timezone.convert(timezone) + def to_datetime_in_timezone(%NaiveDateTime{} = naive, timezone) do + naive + |> DateTime.from_naive!("Etc/UTC") + |> to_datetime_in_timezone(timezone) + end + + def to_datetime_in_timezone(%Date{} = date, timezone) do + date + |> DateTime.new!(~T[00:00:00], "Etc/UTC") + |> to_datetime_in_timezone(timezone) + end + + def to_datetime_in_timezone(%DateTime{} = dt, timezone) do + DateTime.shift_zone!(dt, timezone) end defp build_option(timezone_code, acc, now) do diff --git a/test/plausible/site/sites_test.exs b/test/plausible/site/sites_test.exs index e623ffdc5..e52f1ba59 100644 --- a/test/plausible/site/sites_test.exs +++ b/test/plausible/site/sites_test.exs @@ -2,6 +2,7 @@ defmodule Plausible.SitesTest do use Plausible.DataCase alias Plausible.Sites + doctest Sites, import: true describe "create a site" do test "creates a site" do diff --git a/test/plausible/timezones_test.exs b/test/plausible/timezones_test.exs index 890d2e2f2..4a60e8859 100644 --- a/test/plausible/timezones_test.exs +++ b/test/plausible/timezones_test.exs @@ -3,6 +3,8 @@ defmodule Plausible.TimezonesTest do import Plausible.Timezones + doctest Plausible.Timezones, import: true + test "options/0 returns a list of timezones" do options = options() refute Enum.empty?(options) @@ -23,7 +25,7 @@ defmodule Plausible.TimezonesTest do assert to_utc_datetime(~N[2022-09-11 00:00:00], "Etc/UTC") == ~U[2022-09-11 00:00:00Z] assert to_utc_datetime(~N[2022-09-11 00:00:00], "America/Santiago") == - ~U[2022-09-11 00:00:00Z] + ~U[2022-09-11 04:00:00Z] assert to_utc_datetime(~N[2023-10-29 00:00:00], "Atlantic/Azores") == ~U[2023-10-29 01:00:00Z] end @@ -32,7 +34,9 @@ defmodule Plausible.TimezonesTest do assert to_date_in_timezone(~D[2021-01-03], "Etc/UTC") == ~D[2021-01-03] assert to_date_in_timezone(~U[2015-01-13 13:00:07Z], "Etc/UTC") == ~D[2015-01-13] assert to_date_in_timezone(~N[2015-01-13 13:00:07], "Etc/UTC") == ~D[2015-01-13] - assert to_date_in_timezone(~N[2015-01-13 19:00:07], "Etc/GMT+12") == ~D[2015-01-14] + assert to_date_in_timezone(~N[2015-01-13 19:00:07], "Etc/GMT+12") == ~D[2015-01-13] + assert to_date_in_timezone(~N[2015-01-13 11:00:07], "Etc/GMT+12") == ~D[2015-01-12] + assert to_date_in_timezone(~N[2015-01-13 19:00:07], "Etc/GMT-12") == ~D[2015-01-14] end test "to_datetime_in_timezone/1" do @@ -45,13 +49,13 @@ defmodule Plausible.TimezonesTest do second: 7, calendar: Calendar.ISO, month: 1, - day: 14, + day: 13, year: 2015, minute: 0, hour: 7, - time_zone: "Etc/GMT-12", - zone_abbr: "+12", - utc_offset: 43_200, + time_zone: "Etc/GMT+12", + zone_abbr: "-12", + utc_offset: -43_200, std_offset: 0 } @@ -69,5 +73,29 @@ defmodule Plausible.TimezonesTest do utc_offset: 3600, std_offset: 3600 } + + ambiguous = [ + ~N[2018-10-28 00:00:00], + ~N[2018-10-28 00:30:00], + ~N[2018-10-28 01:00:00], + ~N[2018-10-28 01:30:00] + ] + + assert for(t <- ambiguous, do: inspect(to_datetime_in_timezone(t, "Europe/Copenhagen"))) == [ + "#DateTime<2018-10-28 02:00:00+02:00 CEST Europe/Copenhagen>", + "#DateTime<2018-10-28 02:30:00+02:00 CEST Europe/Copenhagen>", + "#DateTime<2018-10-28 02:00:00+01:00 CET Europe/Copenhagen>", + "#DateTime<2018-10-28 02:30:00+01:00 CET Europe/Copenhagen>" + ] + + gap = [ + ~N[2019-03-31 00:59:59], + ~N[2019-03-31 01:00:00] + ] + + assert for(t <- gap, do: inspect(to_datetime_in_timezone(t, "Europe/Copenhagen"))) == [ + "#DateTime<2019-03-31 01:59:59+01:00 CET Europe/Copenhagen>", + "#DateTime<2019-03-31 03:00:00+02:00 CEST Europe/Copenhagen>" + ] end end