// Copyright 2020 Prometheus Team // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package timeinterval import ( "encoding/json" "errors" "fmt" "os" "regexp" "runtime" "strconv" "strings" "time" "gopkg.in/yaml.v2" ) // TimeInterval describes intervals of time. ContainsTime will tell you if a golang time is contained // within the interval. type TimeInterval struct { Times []TimeRange `yaml:"times,omitempty" json:"times,omitempty"` Weekdays []WeekdayRange `yaml:"weekdays,flow,omitempty" json:"weekdays,omitempty"` DaysOfMonth []DayOfMonthRange `yaml:"days_of_month,flow,omitempty" json:"days_of_month,omitempty"` Months []MonthRange `yaml:"months,flow,omitempty" json:"months,omitempty"` Years []YearRange `yaml:"years,flow,omitempty" json:"years,omitempty"` Location *Location `yaml:"location,flow,omitempty" json:"location,omitempty"` } // TimeRange represents a range of minutes within a 1440 minute day, exclusive of the End minute. A day consists of 1440 minutes. // For example, 4:00PM to End of the day would Begin at 1020 and End at 1440. type TimeRange struct { StartMinute int EndMinute int } // InclusiveRange is used to hold the Beginning and End values of many time interval components. type InclusiveRange struct { Begin int End int } // A WeekdayRange is an inclusive range between [0, 6] where 0 = Sunday. type WeekdayRange struct { InclusiveRange } // A DayOfMonthRange is an inclusive range that may have negative Beginning/End values that represent distance from the End of the month Beginning at -1. type DayOfMonthRange struct { InclusiveRange } // A MonthRange is an inclusive range between [1, 12] where 1 = January. type MonthRange struct { InclusiveRange } // A YearRange is a positive inclusive range. type YearRange struct { InclusiveRange } // A Location is a container for a time.Location, used for custom unmarshalling/validation logic. type Location struct { *time.Location } type yamlTimeRange struct { StartTime string `yaml:"start_time" json:"start_time"` EndTime string `yaml:"end_time" json:"end_time"` } // A range with a Beginning and End that can be represented as strings. type stringableRange interface { setBegin(int) setEnd(int) // Try to map a member of the range into an integer. memberFromString(string) (int, error) } func (ir *InclusiveRange) setBegin(n int) { ir.Begin = n } func (ir *InclusiveRange) setEnd(n int) { ir.End = n } func (ir *InclusiveRange) memberFromString(in string) (out int, err error) { out, err = strconv.Atoi(in) if err != nil { return -1, err } return out, nil } func (r *WeekdayRange) memberFromString(in string) (out int, err error) { out, ok := daysOfWeek[in] if !ok { return -1, fmt.Errorf("%s is not a valid weekday", in) } return out, nil } func (r *MonthRange) memberFromString(in string) (out int, err error) { out, ok := months[in] if !ok { out, err = strconv.Atoi(in) if err != nil { return -1, fmt.Errorf("%s is not a valid month", in) } } return out, nil } var daysOfWeek = map[string]int{ "sunday": 0, "monday": 1, "tuesday": 2, "wednesday": 3, "thursday": 4, "friday": 5, "saturday": 6, } var daysOfWeekInv = map[int]string{ 0: "sunday", 1: "monday", 2: "tuesday", 3: "wednesday", 4: "thursday", 5: "friday", 6: "saturday", } var months = map[string]int{ "january": 1, "february": 2, "march": 3, "april": 4, "may": 5, "june": 6, "july": 7, "august": 8, "september": 9, "october": 10, "november": 11, "december": 12, } var monthsInv = map[int]string{ 1: "january", 2: "february", 3: "march", 4: "april", 5: "may", 6: "june", 7: "july", 8: "august", 9: "september", 10: "october", 11: "november", 12: "december", } // UnmarshalYAML implements the Unmarshaller interface for Location. func (tz *Location) UnmarshalYAML(unmarshal func(interface{}) error) error { var str string if err := unmarshal(&str); err != nil { return err } loc, err := time.LoadLocation(str) if err != nil { if runtime.GOOS == "windows" { if zoneinfo := os.Getenv("ZONEINFO"); zoneinfo != "" { return fmt.Errorf("%w (ZONEINFO=%q)", err, zoneinfo) } return fmt.Errorf("%w (on Windows platforms, you may have to pass the time zone database using the ZONEINFO environment variable, see https://pkg.go.dev/time#LoadLocation for details)", err) } return err } *tz = Location{loc} return nil } // UnmarshalJSON implements the json.Unmarshaler interface for Location. // It delegates to the YAML unmarshaller as it can parse JSON and has validation logic. func (tz *Location) UnmarshalJSON(in []byte) error { return yaml.Unmarshal(in, tz) } // UnmarshalYAML implements the Unmarshaller interface for WeekdayRange. func (r *WeekdayRange) UnmarshalYAML(unmarshal func(interface{}) error) error { var str string if err := unmarshal(&str); err != nil { return err } if err := stringableRangeFromString(str, r); err != nil { return err } if r.Begin > r.End { return errors.New("start day cannot be before end day") } if r.Begin < 0 || r.Begin > 6 { return fmt.Errorf("%s is not a valid day of the week: out of range", str) } if r.End < 0 || r.End > 6 { return fmt.Errorf("%s is not a valid day of the week: out of range", str) } return nil } // UnmarshalJSON implements the json.Unmarshaler interface for WeekdayRange. // It delegates to the YAML unmarshaller as it can parse JSON and has validation logic. func (r *WeekdayRange) UnmarshalJSON(in []byte) error { return yaml.Unmarshal(in, r) } // UnmarshalYAML implements the Unmarshaller interface for DayOfMonthRange. func (r *DayOfMonthRange) UnmarshalYAML(unmarshal func(interface{}) error) error { var str string if err := unmarshal(&str); err != nil { return err } if err := stringableRangeFromString(str, r); err != nil { return err } // Check beginning <= end accounting for negatives day of month indices as well. // Months != 31 days can't be addressed here and are clamped, but at least we can catch blatant errors. if r.Begin == 0 || r.Begin < -31 || r.Begin > 31 { return fmt.Errorf("%d is not a valid day of the month: out of range", r.Begin) } if r.End == 0 || r.End < -31 || r.End > 31 { return fmt.Errorf("%d is not a valid day of the month: out of range", r.End) } // Restricting here prevents errors where begin > end in longer months but not shorter months. if r.Begin < 0 && r.End > 0 { return fmt.Errorf("end day must be negative if start day is negative") } // Check begin <= end. We can't know this for sure when using negative indices // but we can prevent cases where its always invalid (using 28 day minimum length). checkBegin := r.Begin checkEnd := r.End if r.Begin < 0 { checkBegin = 28 + r.Begin } if r.End < 0 { checkEnd = 28 + r.End } if checkBegin > checkEnd { return fmt.Errorf("end day %d is always before start day %d", r.End, r.Begin) } return nil } // UnmarshalJSON implements the json.Unmarshaler interface for DayOfMonthRange. // It delegates to the YAML unmarshaller as it can parse JSON and has validation logic. func (r *DayOfMonthRange) UnmarshalJSON(in []byte) error { return yaml.Unmarshal(in, r) } // UnmarshalYAML implements the Unmarshaller interface for MonthRange. func (r *MonthRange) UnmarshalYAML(unmarshal func(interface{}) error) error { var str string if err := unmarshal(&str); err != nil { return err } if err := stringableRangeFromString(str, r); err != nil { return err } if r.Begin > r.End { begin := monthsInv[r.Begin] end := monthsInv[r.End] return fmt.Errorf("end month %s is before start month %s", end, begin) } return nil } // UnmarshalJSON implements the json.Unmarshaler interface for MonthRange. // It delegates to the YAML unmarshaller as it can parse JSON and has validation logic. func (r *MonthRange) UnmarshalJSON(in []byte) error { return yaml.Unmarshal(in, r) } // UnmarshalYAML implements the Unmarshaller interface for YearRange. func (r *YearRange) UnmarshalYAML(unmarshal func(interface{}) error) error { var str string if err := unmarshal(&str); err != nil { return err } if err := stringableRangeFromString(str, r); err != nil { return err } if r.Begin > r.End { return fmt.Errorf("end year %d is before start year %d", r.End, r.Begin) } return nil } // UnmarshalJSON implements the json.Unmarshaler interface for YearRange. // It delegates to the YAML unmarshaller as it can parse JSON and has validation logic. func (r *YearRange) UnmarshalJSON(in []byte) error { return yaml.Unmarshal(in, r) } // UnmarshalYAML implements the Unmarshaller interface for TimeRanges. func (tr *TimeRange) UnmarshalYAML(unmarshal func(interface{}) error) error { var y yamlTimeRange if err := unmarshal(&y); err != nil { return err } if y.EndTime == "" || y.StartTime == "" { return errors.New("both start and end times must be provided") } start, err := parseTime(y.StartTime) if err != nil { return err } end, err := parseTime(y.EndTime) if err != nil { return err } if start >= end { return errors.New("start time cannot be equal or greater than end time") } tr.StartMinute, tr.EndMinute = start, end return nil } // UnmarshalJSON implements the json.Unmarshaler interface for Timerange. // It delegates to the YAML unmarshaller as it can parse JSON and has validation logic. func (tr *TimeRange) UnmarshalJSON(in []byte) error { return yaml.Unmarshal(in, tr) } // MarshalYAML implements the yaml.Marshaler interface for WeekdayRange. func (r WeekdayRange) MarshalYAML() (interface{}, error) { bytes, err := r.MarshalText() return string(bytes), err } // MarshalText implements the econding.TextMarshaler interface for WeekdayRange. // It converts the range into a colon-separated string, or a single weekday if possible. // e.g. "monday:friday" or "saturday". func (r WeekdayRange) MarshalText() ([]byte, error) { beginStr, ok := daysOfWeekInv[r.Begin] if !ok { return nil, fmt.Errorf("unable to convert %d into weekday string", r.Begin) } if r.Begin == r.End { return []byte(beginStr), nil } endStr, ok := daysOfWeekInv[r.End] if !ok { return nil, fmt.Errorf("unable to convert %d into weekday string", r.End) } rangeStr := fmt.Sprintf("%s:%s", beginStr, endStr) return []byte(rangeStr), nil } // MarshalYAML implements the yaml.Marshaler interface for TimeRange. func (tr TimeRange) MarshalYAML() (out interface{}, err error) { startHr := tr.StartMinute / 60 endHr := tr.EndMinute / 60 startMin := tr.StartMinute % 60 endMin := tr.EndMinute % 60 startStr := fmt.Sprintf("%02d:%02d", startHr, startMin) endStr := fmt.Sprintf("%02d:%02d", endHr, endMin) yTr := yamlTimeRange{startStr, endStr} return interface{}(yTr), err } // MarshalJSON implements the json.Marshaler interface for TimeRange. func (tr TimeRange) MarshalJSON() (out []byte, err error) { startHr := tr.StartMinute / 60 endHr := tr.EndMinute / 60 startMin := tr.StartMinute % 60 endMin := tr.EndMinute % 60 startStr := fmt.Sprintf("%02d:%02d", startHr, startMin) endStr := fmt.Sprintf("%02d:%02d", endHr, endMin) yTr := yamlTimeRange{startStr, endStr} return json.Marshal(yTr) } // MarshalText implements the econding.TextMarshaler interface for Location. // It marshals a Location back into a string that represents a time.Location. func (tz Location) MarshalText() ([]byte, error) { if tz.Location == nil { return nil, fmt.Errorf("unable to convert nil location into string") } return []byte(tz.Location.String()), nil } // MarshalYAML implements the yaml.Marshaler interface for Location. func (tz Location) MarshalYAML() (interface{}, error) { bytes, err := tz.MarshalText() return string(bytes), err } // MarshalJSON implements the json.Marshaler interface for Location. func (tz Location) MarshalJSON() (out []byte, err error) { return json.Marshal(tz.String()) } // MarshalText implements the encoding.TextMarshaler interface for InclusiveRange. // It converts the struct into a colon-separated string, or a single element if // appropriate. e.g. "monday:friday" or "monday" func (ir InclusiveRange) MarshalText() ([]byte, error) { if ir.Begin == ir.End { return []byte(strconv.Itoa(ir.Begin)), nil } out := fmt.Sprintf("%d:%d", ir.Begin, ir.End) return []byte(out), nil } // MarshalYAML implements the yaml.Marshaler interface for InclusiveRange. func (ir InclusiveRange) MarshalYAML() (interface{}, error) { bytes, err := ir.MarshalText() return string(bytes), err } // TimeLayout specifies the layout to be used in time.Parse() calls for time intervals. const TimeLayout = "15:04" var ( validTime = "^((([01][0-9])|(2[0-3])):[0-5][0-9])$|(^24:00$)" validTimeRE = regexp.MustCompile(validTime) ) // Given a time, determines the number of days in the month that time occurs in. func daysInMonth(t time.Time) int { monthStart := time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, t.Location()) monthEnd := monthStart.AddDate(0, 1, 0) diff := monthEnd.Sub(monthStart) return int(diff.Hours() / 24) } func clamp(n, min, max int) int { if n <= min { return min } if n >= max { return max } return n } // ContainsTime returns true if the TimeInterval contains the given time, otherwise returns false. func (tp TimeInterval) ContainsTime(t time.Time) bool { if tp.Location != nil { t = t.In(tp.Location.Location) } if tp.Times != nil { in := false for _, validMinutes := range tp.Times { if (t.Hour()*60+t.Minute()) >= validMinutes.StartMinute && (t.Hour()*60+t.Minute()) < validMinutes.EndMinute { in = true break } } if !in { return false } } if tp.DaysOfMonth != nil { in := false for _, validDates := range tp.DaysOfMonth { var begin, end int daysInMonth := daysInMonth(t) if validDates.Begin < 0 { begin = daysInMonth + validDates.Begin + 1 } else { begin = validDates.Begin } if validDates.End < 0 { end = daysInMonth + validDates.End + 1 } else { end = validDates.End } // Skip clamping if the beginning date is after the end of the month. if begin > daysInMonth { continue } // Clamp to the boundaries of the month to prevent crossing into other months. begin = clamp(begin, -1*daysInMonth, daysInMonth) end = clamp(end, -1*daysInMonth, daysInMonth) if t.Day() >= begin && t.Day() <= end { in = true break } } if !in { return false } } if tp.Months != nil { in := false for _, validMonths := range tp.Months { if t.Month() >= time.Month(validMonths.Begin) && t.Month() <= time.Month(validMonths.End) { in = true break } } if !in { return false } } if tp.Weekdays != nil { in := false for _, validDays := range tp.Weekdays { if t.Weekday() >= time.Weekday(validDays.Begin) && t.Weekday() <= time.Weekday(validDays.End) { in = true break } } if !in { return false } } if tp.Years != nil { in := false for _, validYears := range tp.Years { if t.Year() >= validYears.Begin && t.Year() <= validYears.End { in = true break } } if !in { return false } } return true } // Converts a string of the form "HH:MM" into the number of minutes elapsed in the day. func parseTime(in string) (mins int, err error) { if !validTimeRE.MatchString(in) { return 0, fmt.Errorf("couldn't parse timestamp %s, invalid format", in) } timestampComponents := strings.Split(in, ":") if len(timestampComponents) != 2 { return 0, fmt.Errorf("invalid timestamp format: %s", in) } timeStampHours, err := strconv.Atoi(timestampComponents[0]) if err != nil { return 0, err } timeStampMinutes, err := strconv.Atoi(timestampComponents[1]) if err != nil { return 0, err } if timeStampHours < 0 || timeStampHours > 24 || timeStampMinutes < 0 || timeStampMinutes > 60 { return 0, fmt.Errorf("timestamp %s out of range", in) } // Timestamps are stored as minutes elapsed in the day, so multiply hours by 60. mins = timeStampHours*60 + timeStampMinutes return mins, nil } // Converts a range that can be represented as strings (e.g. monday:wednesday) into an equivalent integer-represented range. func stringableRangeFromString(in string, r stringableRange) (err error) { in = strings.ToLower(in) if strings.ContainsRune(in, ':') { components := strings.Split(in, ":") if len(components) != 2 { return fmt.Errorf("couldn't parse range %s, invalid format", in) } start, err := r.memberFromString(components[0]) if err != nil { return err } End, err := r.memberFromString(components[1]) if err != nil { return err } r.setBegin(start) r.setEnd(End) return nil } val, err := r.memberFromString(in) if err != nil { return err } r.setBegin(val) r.setEnd(val) return nil }