Type: "Expiry"

Introduction

The Expiry type is a Lua table that describes when an expiry should occur. When an actual expiry is calculated from this table of data the expiry becomes fixed in time as an actual date and time.

An Expiry has the following table fields. All fields are optional, however at least one of days, hours, seconds, weeks, minutes, or months is expected to actually change any date calculated from the expiry definition.

When rounding an expiry date/time the Expiry object can determine exactly how the rounding should occur based on the round_method, round_to and round_boundary fields.

The round_method determines whether this rounding applies up or down. If not given, no rounding occurs.

When the round_to field is given, the OCS calculates the expiry point to the second based on the minutes, days etc. fields, but then the OCS will round the expiry period to the unit of time given by the round_to field.

For example, if round_to is given as days then the expiry will (by default) round to the midnight boundary. Note that if the rounding would give the same time as the initial point from which rounding is calculated, no rounding occurs.

The round_boundary determines what part of the rounding period should be the actual boundary. The interpretation of this depends on the round_to. When rounding to the minute, what second is considered the “end” (or “start”) of a minute. For the hour, which minute of the hour. For the day, which hour of the day. For week, which day of the week for month, which day of the month. By default, the natural starting point (Monday in the case of a week) is considered.

Complex leap year and end of month cases are handled by calculating the expiry up to the last day of the appropriate month. For example, if an expiry calculation of “1 month” is set, but the start point is the 31st January, then the 28th (or 29th) February is selected as the expiry date.

Example

An expiry is set to 1 week from now, but round to the earlier Wednesday:

    ...
    local expiry = {
        weeks = 1,
        round_to = "weeks",
        round_method = "down",
        round_boundary = 3
    }
    lifecycle.set_transition_out_time(expiry)
    ...

Using this expiry, the OCS will select the next calendar day which is a Wednesday and expire at midnight on that Wednesday. This would give an actual expiry period of between minutes (if it were just before Wednesday) or 7 days.

API Methods

.calculate_expiry

The calculate_expiry method of the OCS API applies the expiry to a date & time.

    local ocs = require "ocs.n2ocs"
    local plusonemonth = ocs.calculate_expiry ( { months = 1 } )
    ...

This method returns a floating point number representing the seconds and milliseconds as calculated as the expiry from the date/time given.