|
| 1 | +%% This Source Code Form is subject to the terms of the Mozilla Public |
| 2 | +%% License, v. 2.0. If a copy of the MPL was not distributed with this |
| 3 | +%% file, You can obtain one at https://mozilla.org/MPL/2.0/. |
| 4 | +%% |
| 5 | +%% Copyright (c) 2021-2022 VMware, Inc. or its affiliates. All rights reserved. |
| 6 | +%% |
| 7 | + |
| 8 | +%% @doc Khepri event filters. |
| 9 | + |
| 10 | +-module(khepri_evf). |
| 11 | + |
| 12 | +-include("src/internal.hrl"). |
| 13 | + |
| 14 | +-export([tree/1, tree/2, |
| 15 | + wrap/1, |
| 16 | + get_priority/1, |
| 17 | + set_priority/2]). |
| 18 | + |
| 19 | +-type tree_event_filter() :: #evf_tree{}. |
| 20 | +%% A tree event filter. |
| 21 | +%% |
| 22 | +%% It takes a path pattern to monitor and optionally properties. |
| 23 | + |
| 24 | +-type tree_event_filter_props() :: #{on_actions => [create | update | delete], |
| 25 | + priority => khepri_evf:priority()}. |
| 26 | +%% Tree event filter properties. |
| 27 | +%% |
| 28 | +%% The properties are: |
| 29 | +%% <ul> |
| 30 | +%% <li>`on_actions': a list of actions to filter among `create', `update' and |
| 31 | +%% `delete'; the default is to react to all of them.</li> |
| 32 | +%% <li>`priority': a {@link priority()}</li> |
| 33 | +%% </ul> |
| 34 | +%% |
| 35 | +%% A Khepri path, wether it is a native path or a Unix-like path, can be used |
| 36 | +%% as a tree event filter. It will be automatically converted to a tree event |
| 37 | +%% filter with default properties. |
| 38 | + |
| 39 | +-type event_filter() :: tree_event_filter(). |
| 40 | +%% An event filter. |
| 41 | +%% |
| 42 | +%% The following event filters are supported: |
| 43 | +%% <ul> |
| 44 | +%% <li>Tree event filter ({@link tree_event_filter()}</li> |
| 45 | +%% </ul> |
| 46 | +%% |
| 47 | +%% An event filter can be explicitly constructed using the functions provided |
| 48 | +%% in this module. However, some common types will be automatically detected |
| 49 | +%% and converted to an event filter with default properties. See each event |
| 50 | +%% filter type for more details. |
| 51 | + |
| 52 | +-type priority() :: integer(). |
| 53 | +%% An event filter priority. |
| 54 | +%% |
| 55 | +%% This is an integer to prioritize event filters: the greater the priority, |
| 56 | +%% the more it is prioritized. Negative integers are allowed. |
| 57 | +%% |
| 58 | +%% The default priority is 0. |
| 59 | + |
| 60 | +-export_type([event_filter/0, |
| 61 | + tree_event_filter/0, |
| 62 | + tree_event_filter_props/0, |
| 63 | + priority/0]). |
| 64 | + |
| 65 | +-spec tree(PathPattern) -> EventFilter when |
| 66 | + PathPattern :: khepri_path:pattern() | string(), |
| 67 | + EventFilter :: tree_event_filter(). |
| 68 | +%% @doc Constructs a tree event filter. |
| 69 | +%% |
| 70 | +%% @see tree/2. |
| 71 | + |
| 72 | +tree(PathPattern) -> |
| 73 | + tree(PathPattern, #{}). |
| 74 | + |
| 75 | +-spec tree(PathPattern, Props) -> EventFilter when |
| 76 | + PathPattern :: khepri_path:pattern() | string(), |
| 77 | + Props :: tree_event_filter_props(), |
| 78 | + EventFilter :: tree_event_filter(). |
| 79 | +%% @doc Constructs a tree event filter. |
| 80 | +%% |
| 81 | +%% @see tree_event_filter(). |
| 82 | + |
| 83 | +tree(PathPattern, Props) -> |
| 84 | + PathPattern1 = khepri_path:from_string(PathPattern), |
| 85 | + #evf_tree{path = PathPattern1, |
| 86 | + props = Props}. |
| 87 | + |
| 88 | +-spec wrap(Input) -> EventFilter when |
| 89 | + Input :: event_filter() | khepri_path:pattern() | string(), |
| 90 | + EventFilter :: event_filter(). |
| 91 | +%% @doc Automatically detects the event filter type and ensures it is wrapped |
| 92 | +%% in one of the internal types. |
| 93 | +%% |
| 94 | +%% @param Input an already created event filter, or any term which can be |
| 95 | +%% automatically converted to an event filter. |
| 96 | +%% |
| 97 | +%% @returns the created event filter. |
| 98 | + |
| 99 | +wrap(EventFilter) when ?IS_KHEPRI_EVENT_FILTER(EventFilter) -> |
| 100 | + EventFilter; |
| 101 | +wrap(PathPattern) when is_list(PathPattern) -> |
| 102 | + tree(PathPattern). |
| 103 | + |
| 104 | +-spec get_priority(EventFilter) -> Priority when |
| 105 | + EventFilter :: event_filter(), |
| 106 | + Priority :: priority(). |
| 107 | +%% @doc Returns the priority of the event filter. |
| 108 | +%% |
| 109 | +%% @param EventFilter the event filter to update. |
| 110 | +%% |
| 111 | +%% @returns the priority. |
| 112 | + |
| 113 | +get_priority(#evf_tree{props = Props}) -> |
| 114 | + get_priority1(Props). |
| 115 | + |
| 116 | +get_priority1(#{priority := Priority}) -> Priority; |
| 117 | +get_priority1(_) -> 0. |
| 118 | + |
| 119 | +-spec set_priority(EventFilter, Priority) -> EventFilter when |
| 120 | + EventFilter :: event_filter(), |
| 121 | + Priority :: priority(). |
| 122 | +%% @doc Sets the priority of the event filter. |
| 123 | +%% |
| 124 | +%% @param EventFilter the event filter to update. |
| 125 | +%% @param Priority the new priority. |
| 126 | +%% |
| 127 | +%% @returns the updated event filter. |
| 128 | + |
| 129 | +set_priority(#evf_tree{props = Props} = EventFilter, Priority) -> |
| 130 | + Props1 = set_priority1(Props, Priority), |
| 131 | + EventFilter#evf_tree{props = Props1}. |
| 132 | + |
| 133 | +set_priority1(Props, Priority) when is_integer(Priority) -> |
| 134 | + Props#{priority => Priority}. |
0 commit comments