// Package schedule provides types for scheduling. package schedule import ( "encoding/json" "fmt" "time" "github.com/AdguardTeam/AdGuardHome/internal/aghhttp" "github.com/AdguardTeam/golibs/errors" "github.com/AdguardTeam/golibs/timeutil" "gopkg.in/yaml.v3" ) // Weekly is a schedule for one week. Each day of the week has one range with // a beginning and an end. type Weekly struct { // location is used to calculate the offsets of the day ranges. location *time.Location // days are the day ranges of this schedule. The indexes of this array are // the [time.Weekday] values. days [7]dayRange } // EmptyWeekly creates empty weekly schedule with local time zone. func EmptyWeekly() (w *Weekly) { return &Weekly{ location: time.Local, } } // FullWeekly creates full weekly schedule with local time zone. // // TODO(s.chzhen): Consider moving into tests. func FullWeekly() (w *Weekly) { fullDay := dayRange{start: 0, end: maxDayRange} return &Weekly{ location: time.Local, days: [7]dayRange{ time.Sunday: fullDay, time.Monday: fullDay, time.Tuesday: fullDay, time.Wednesday: fullDay, time.Thursday: fullDay, time.Friday: fullDay, time.Saturday: fullDay, }, } } // Clone returns a deep copy of a weekly. func (w *Weekly) Clone() (c *Weekly) { if w == nil { return nil } // NOTE: Do not use time.LoadLocation, because the results will be // different on time zone database update. return &Weekly{ location: w.location, days: w.days, } } // Contains returns true if t is within the corresponding day range of the // schedule in the schedule's time zone. func (w *Weekly) Contains(t time.Time) (ok bool) { t = t.In(w.location) wd := t.Weekday() dr := w.days[wd] // Calculate the offset of the day range. // // NOTE: Do not use [time.Truncate] since it requires UTC time zone. y, m, d := t.Date() day := time.Date(y, m, d, 0, 0, 0, 0, w.location) offset := t.Sub(day) return dr.contains(offset) } // type check var _ json.Unmarshaler = (*Weekly)(nil) // UnmarshalJSON implements the [json.Unmarshaler] interface for *Weekly. func (w *Weekly) UnmarshalJSON(data []byte) (err error) { conf := &weeklyConfigJSON{} err = json.Unmarshal(data, conf) if err != nil { return err } weekly := Weekly{} weekly.location, err = time.LoadLocation(conf.TimeZone) if err != nil { return err } days := []*dayConfigJSON{ time.Sunday: conf.Sunday, time.Monday: conf.Monday, time.Tuesday: conf.Tuesday, time.Wednesday: conf.Wednesday, time.Thursday: conf.Thursday, time.Friday: conf.Friday, time.Saturday: conf.Saturday, } for i, d := range days { var r dayRange if d != nil { r = dayRange{ start: time.Duration(d.Start), end: time.Duration(d.End), } } err = w.validate(r) if err != nil { return fmt.Errorf("weekday %s: %w", time.Weekday(i), err) } weekly.days[i] = r } *w = weekly return nil } // type check var _ yaml.Unmarshaler = (*Weekly)(nil) // UnmarshalYAML implements the [yaml.Unmarshaler] interface for *Weekly. func (w *Weekly) UnmarshalYAML(value *yaml.Node) (err error) { conf := &weeklyConfigYAML{} err = value.Decode(conf) if err != nil { // Don't wrap the error since it's informative enough as is. return err } weekly := Weekly{} weekly.location, err = time.LoadLocation(conf.TimeZone) if err != nil { // Don't wrap the error since it's informative enough as is. return err } days := []dayConfigYAML{ time.Sunday: conf.Sunday, time.Monday: conf.Monday, time.Tuesday: conf.Tuesday, time.Wednesday: conf.Wednesday, time.Thursday: conf.Thursday, time.Friday: conf.Friday, time.Saturday: conf.Saturday, } for i, d := range days { r := dayRange{ start: time.Duration(d.Start), end: time.Duration(d.End), } err = w.validate(r) if err != nil { return fmt.Errorf("weekday %s: %w", time.Weekday(i), err) } weekly.days[i] = r } *w = weekly return nil } // weeklyConfigYAML is the YAML configuration structure of Weekly. type weeklyConfigYAML struct { // TimeZone is the local time zone. TimeZone string `yaml:"time_zone"` // Days of the week. Sunday dayConfigYAML `yaml:"sun,omitempty"` Monday dayConfigYAML `yaml:"mon,omitempty"` Tuesday dayConfigYAML `yaml:"tue,omitempty"` Wednesday dayConfigYAML `yaml:"wed,omitempty"` Thursday dayConfigYAML `yaml:"thu,omitempty"` Friday dayConfigYAML `yaml:"fri,omitempty"` Saturday dayConfigYAML `yaml:"sat,omitempty"` } // dayConfigYAML is the YAML configuration structure of dayRange. type dayConfigYAML struct { Start timeutil.Duration `yaml:"start"` End timeutil.Duration `yaml:"end"` } // maxDayRange is the maximum value for day range end. const maxDayRange = 24 * time.Hour // validate returns the day range rounding errors, if any. func (w *Weekly) validate(r dayRange) (err error) { defer func() { err = errors.Annotate(err, "bad day range: %w") }() err = r.validate() if err != nil { // Don't wrap the error since it's informative enough as is. return err } start := r.start.Truncate(time.Minute) end := r.end.Truncate(time.Minute) switch { case start != r.start: return fmt.Errorf("start %s isn't rounded to minutes", r.start) case end != r.end: return fmt.Errorf("end %s isn't rounded to minutes", r.end) default: return nil } } // type check var _ json.Marshaler = (*Weekly)(nil) // MarshalJSON implements the [json.Marshaler] interface for *Weekly. func (w *Weekly) MarshalJSON() (data []byte, err error) { c := &weeklyConfigJSON{ TimeZone: w.location.String(), Sunday: w.days[time.Sunday].toDayConfigJSON(), Monday: w.days[time.Monday].toDayConfigJSON(), Tuesday: w.days[time.Tuesday].toDayConfigJSON(), Wednesday: w.days[time.Wednesday].toDayConfigJSON(), Thursday: w.days[time.Thursday].toDayConfigJSON(), Friday: w.days[time.Friday].toDayConfigJSON(), Saturday: w.days[time.Saturday].toDayConfigJSON(), } return json.Marshal(c) } // type check var _ yaml.Marshaler = (*Weekly)(nil) // MarshalYAML implements the [yaml.Marshaler] interface for *Weekly. func (w *Weekly) MarshalYAML() (v any, err error) { return weeklyConfigYAML{ TimeZone: w.location.String(), Sunday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Sunday].start), End: timeutil.Duration(w.days[time.Sunday].end), }, Monday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Monday].start), End: timeutil.Duration(w.days[time.Monday].end), }, Tuesday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Tuesday].start), End: timeutil.Duration(w.days[time.Tuesday].end), }, Wednesday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Wednesday].start), End: timeutil.Duration(w.days[time.Wednesday].end), }, Thursday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Thursday].start), End: timeutil.Duration(w.days[time.Thursday].end), }, Friday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Friday].start), End: timeutil.Duration(w.days[time.Friday].end), }, Saturday: dayConfigYAML{ Start: timeutil.Duration(w.days[time.Saturday].start), End: timeutil.Duration(w.days[time.Saturday].end), }, }, nil } // dayRange represents a single interval within a day. The interval begins at // start and ends before end. That is, it contains a time point T if start <= // T < end. type dayRange struct { // start is an offset from the beginning of the day. It must be greater // than or equal to zero and less than 24h. start time.Duration // end is an offset from the beginning of the day. It must be greater than // or equal to zero and less than or equal to 24h. end time.Duration } // validate returns the day range validation errors, if any. func (r dayRange) validate() (err error) { switch { case r == dayRange{}: return nil case r.start < 0: return fmt.Errorf("start %s is negative", r.start) case r.end < 0: return fmt.Errorf("end %s is negative", r.end) case r.start >= r.end: return fmt.Errorf("start %s is greater or equal to end %s", r.start, r.end) case r.start >= maxDayRange: return fmt.Errorf("start %s is greater or equal to %s", r.start, maxDayRange) case r.end > maxDayRange: return fmt.Errorf("end %s is greater than %s", r.end, maxDayRange) default: return nil } } // contains returns true if start <= offset < end, where offset is the time // duration from the beginning of the day. func (r *dayRange) contains(offset time.Duration) (ok bool) { return r.start <= offset && offset < r.end } // toDayConfigJSON returns nil if the day range is empty, otherwise returns // initialized JSON configuration of the day range. func (r dayRange) toDayConfigJSON() (j *dayConfigJSON) { if (r == dayRange{}) { return nil } return &dayConfigJSON{ Start: aghhttp.JSONDuration(r.start), End: aghhttp.JSONDuration(r.end), } } // weeklyConfigJSON is the JSON configuration structure of Weekly. type weeklyConfigJSON struct { // Days of the week. Sunday *dayConfigJSON `json:"sun,omitempty"` Monday *dayConfigJSON `json:"mon,omitempty"` Tuesday *dayConfigJSON `json:"tue,omitempty"` Wednesday *dayConfigJSON `json:"wed,omitempty"` Thursday *dayConfigJSON `json:"thu,omitempty"` Friday *dayConfigJSON `json:"fri,omitempty"` Saturday *dayConfigJSON `json:"sat,omitempty"` // TimeZone is the local time zone. TimeZone string `json:"time_zone"` } // dayConfigJSON is the JSON configuration structure of dayRange. type dayConfigJSON struct { Start aghhttp.JSONDuration `json:"start"` End aghhttp.JSONDuration `json:"end"` }