PMG/RuleDB/Object.pm

   1 package PMG::RuleDB::Object;
   2
   3 use strict;
   4 use warnings;
   5 use DBI;
   6
   7 use PMG::Utils;
   8 use PMG::RuleDB;
   9
  10 sub new {
  11     my ($type, $otype, $ogroup) = @_;
  12
  13     $otype //= 0;
  14
  15     my $self = {
  16         otype => $otype,
  17         ogroup => $ogroup,
  18     };
  19
  20     bless $self, $type;
  21
  22     return $self;
  23 }
  24
  25 sub save {
  26     die "never call this method: ERROR";
  27 }
  28
  29 sub update {
  30     my ($self, $param) = @_;
  31
  32     die "never call this method: ERROR";
  33 }
  34
  35 sub load_attr {
  36     die "never call this method: ERROR";
  37 }
  38
  39 sub who_match {
  40     die "never call this method: ERROR";
  41 }
  42
  43 sub when_match {
  44     die "never call this method: ERROR";
  45 }
  46
  47 sub what_match {
  48     die "never call this method: ERROR";
  49 }
  50
  51 sub execute {
  52     die "never call this method: ERROR";
  53 }
  54
  55 sub final {
  56     return undef;
  57 }
  58
  59 sub priority {
  60     return 0;
  61 }
  62
  63 sub oisedit {
  64     return 1;
  65 }
  66
  67 sub ogroup {
  68     my ($self, $v) = @_;
  69
  70     if (defined ($v)) {
  71         $self->{ogroup} = $v;
  72     }
  73
  74     $self->{ogroup};
  75 }
  76
  77 sub otype {
  78     my $self = shift;
  79
  80     $self->{otype};
  81 }
  82
  83 sub otype_text {
  84     my $self = shift;
  85
  86     return "object";
  87 }
  88
  89 # some who object only matches 'receivers'
  90 sub receivertest {
  91     return 0;
  92 }
  93
  94 sub oclass {
  95     die "never call this method: ERROR";
  96 }
  97
  98 sub id {
  99     my $self = shift;
 100
 101     $self->{id};
 102 }
 103
 104 sub short_desc {
 105     return "basic object";
 106 }
 107
 108 sub properties {
 109     die "never call this method: ERROR";
 110 }
 111
 112 sub get {
 113     my ($self) = @_;
 114
 115     return undef;
 116 }
 117
 118 sub get_data {
 119     my ($self) = @_;
 120
 121     my $data = $self->get() // {};
 122
 123     $data->{id} = $self->{id};
 124     $data->{ogroup} = $self->{ogroup};
 125     $data->{otype} = $self->otype();
 126     $data->{otype_text} = $self->otype_text();
 127     $data->{receivertest} = $self->receivertest();
 128     $data->{descr} = $self->short_desc();
 129
 130     return $data;
 131 }
 132
 133 sub register_api {
 134     my ($class, $apiclass, $name, $path, $use_greylist_gid) = @_;
 135
 136     $path //= $name;
 137
 138     my $otype = $class->otype();
 139
 140     my $otype_text = $class->otype_text();
 141
 142     my $properties = $class->properties();
 143
 144     my $create_properties = {};
 145     my $update_properties = {
 146         id => {
 147             description => "Object ID.",
 148             type => 'integer',
 149         },
 150     };
 151     my $read_properties = {
 152         id => {
 153             description => "Object ID.",
 154             type => 'integer',
 155         },
 156     };
 157
 158     if (!$use_greylist_gid) {
 159         $read_properties->{ogroup} = $create_properties->{ogroup} = $update_properties->{ogroup} = {
 160             description => "Object Groups ID.",
 161             type => 'integer',
 162         };
 163     };
 164
 165     foreach my $key (keys %$properties) {
 166         $create_properties->{$key} = $properties->{$key};
 167         $update_properties->{$key} = $properties->{$key};
 168     }
 169
 170     $apiclass->register_method ({
 171         name => $name,
 172         path => $path,
 173         method => 'POST',
 174         description => "Add '$otype_text' object.",
 175         proxyto => 'master',
 176         protected => 1,
 177         parameters => {
 178             additionalProperties => 0,
 179             properties => $create_properties,
 180         },
 181         returns => {
 182             description => "The object ID.",
 183             type => 'integer',
 184         },
 185         code => sub {
 186             my ($param) = @_;
 187
 188             my $rdb = PMG::RuleDB->new();
 189
 190             my $gid = $use_greylist_gid ?
 191                 $rdb->greylistexclusion_groupid() : $param->{ogroup};
 192
 193             my $obj = $rdb->get_object($otype);
 194             $obj->{ogroup} = $gid;
 195
 196             $obj->update($param);
 197
 198             my $id = $obj->save($rdb);
 199
 200             if ($use_greylist_gid) {
 201                 PMG::DBTools::reload_ruledb($rdb);
 202             } else {
 203                 PMG::DBTools::reload_ruledb();
 204             }
 205
 206             return $id;
 207         }});
 208
 209     $apiclass->register_method ({
 210         name => "read_$name",
 211         path => "$path/{id}",
 212         method => 'GET',
 213         description => "Read '$otype_text' object settings.",
 214         proxyto => 'master',
 215         parameters => {
 216             additionalProperties => 0,
 217             properties => $read_properties,
 218         },
 219         returns => {
 220             type => "object",
 221             properties => {
 222                 id => { type => 'integer'},
 223             },
 224         },
 225         code => sub {
 226             my ($param) = @_;
 227
 228             my $rdb = PMG::RuleDB->new();
 229
 230             my $gid = $use_greylist_gid ?
 231                 $rdb->greylistexclusion_groupid() : $param->{ogroup};
 232
 233             my $obj = $rdb->load_object_full($param->{id}, $gid, $otype);
 234
 235             return $obj->get_data();
 236         }});
 237
 238     $apiclass->register_method ({
 239         name => "update_$name",
 240         path => "$path/{id}",
 241         method => 'PUT',
 242         description => "Update '$otype_text' object.",
 243         proxyto => 'master',
 244         protected => 1,
 245         parameters => {
 246             additionalProperties => 0,
 247             properties => $update_properties,
 248         },
 249         returns => { type => 'null' },
 250         code => sub {
 251             my ($param) = @_;
 252
 253             my $rdb = PMG::RuleDB->new();
 254
 255             my $gid = $use_greylist_gid ?
 256                 $rdb->greylistexclusion_groupid() : $param->{ogroup};
 257
 258             my $obj = $rdb->load_object_full($param->{id}, $gid, $otype);
 259
 260             $obj->update($param);
 261
 262             $obj->save($rdb);
 263
 264             if ($use_greylist_gid) {
 265                 PMG::DBTools::reload_ruledb($rdb);
 266             } else {
 267                 PMG::DBTools::reload_ruledb();
 268             }
 269
 270             return undef;
 271         }});
 272
 273 }
 274
 275 1;
 276
 277 __END__
 278
 279 =head1 PMG::RuleDB::Object
 280
 281 The Proxmox Rules consists of Objects. There are several classes of Objects. Ech such class has a method to check if the object 'matches'.
 282
 283 =head2 WHO Objects ($obj->oclass() eq 'who')
 284
 285 Who sent the mail, who is the receiver?
 286
 287 =head3  $obj->who_match ($addr)
 288
 289 Returns true if $addr belongs to this objects. $addr is a text string representing the email address you want to check.
 290
 291 =over
 292
 293 =item *
 294
 295 EMail: the only attribute is a regex to test email addresses
 296
 297 =back
 298
 299 =head2 WHEN Objects ($obj->oclass() eq 'when')
 300
 301 Used to test for a certain daytime
 302
 303 =head3  $obj->when_match ($time)
 304
 305 Return true if $time matches the when object constraints. $time is an integer like returned by the time() system call (or generated with POSIX::mktime()).
 306
 307 =over
 308
 309 =item *
 310
 311 TimeFrame: specifies a start and a end time
 312
 313 =back
 314
 315 =head2 WHAT Objects ($obj->oclass() eq 'what')
 316
 317 mail content tests
 318
 319 =head2 ACTION Objects ($obj->oclass() eq 'action')
 320
 321 actions which can be executed
 322
 323 =head3 $obj->execute ($mod_group, $queue, $ruledb, $mod_group, $targets, $msginfo, $vars, $marks)
 324
 325 Execute the action code. $target is a array reference containing all
 326 matching targets.
 327
 328 =head2 Common Methods
 329
 330 =head3 $obj->oclass()
 331
 332 Returns 'who', 'when' 'what' or 'action';
 333
 334 =head3 $obj->short_desc()
 335
 336 Returns a short text describing the contents of the object. This is used
 337 for debugging purposes.
 338
 339 =head3 $obj->otype
 340
 341 Returns an integer representing the Type of the objects. This integer
 342 is used in the database to uniquely identify object types.
 343
 344 =head3 $obj->id
 345
 346 Returns the unique database ID of the object. undef means the object is not jet stored in the databse.
 347
 348 =head3 $obj->final()
 349
 350 Return true if the object is an action and the action is final, i.e. the action stops further rule processing for all matching targets.
 351
 352 =head3 $obj->priority()
 353
 354 Return a priority between 0 and 100. This is currently used to sort action objects by priority.
 355