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         permissions => { check => [ 'admin' ] },
 178         parameters => {
 179             additionalProperties => 0,
 180             properties => $create_properties,
 181         },
 182         returns => {
 183             description => "The object ID.",
 184             type => 'integer',
 185         },
 186         code => sub {
 187             my ($param) = @_;
 188
 189             my $rdb = PMG::RuleDB->new();
 190
 191             my $gid = $use_greylist_gid ?
 192                 $rdb->greylistexclusion_groupid() : $param->{ogroup};
 193
 194             my $obj = $rdb->get_object($otype);
 195             $obj->{ogroup} = $gid;
 196
 197             $obj->update($param);
 198
 199             my $id = $obj->save($rdb);
 200
 201             if ($use_greylist_gid) {
 202                 PMG::DBTools::reload_ruledb($rdb);
 203             } else {
 204                 PMG::DBTools::reload_ruledb();
 205             }
 206
 207             return $id;
 208         }});
 209
 210     $apiclass->register_method ({
 211         name => "read_$name",
 212         path => "$path/{id}",
 213         method => 'GET',
 214         description => "Read '$otype_text' object settings.",
 215         proxyto => 'master',
 216         permissions => { check => [ 'admin', 'audit' ] },
 217         parameters => {
 218             additionalProperties => 0,
 219             properties => $read_properties,
 220         },
 221         returns => {
 222             type => "object",
 223             properties => {
 224                 id => { type => 'integer'},
 225             },
 226         },
 227         code => sub {
 228             my ($param) = @_;
 229
 230             my $rdb = PMG::RuleDB->new();
 231
 232             my $gid = $use_greylist_gid ?
 233                 $rdb->greylistexclusion_groupid() : $param->{ogroup};
 234
 235             my $obj = $rdb->load_object_full($param->{id}, $gid, $otype);
 236
 237             return $obj->get_data();
 238         }});
 239
 240     $apiclass->register_method ({
 241         name => "update_$name",
 242         path => "$path/{id}",
 243         method => 'PUT',
 244         description => "Update '$otype_text' object.",
 245         proxyto => 'master',
 246         permissions => { check => [ 'admin' ] },
 247         protected => 1,
 248         parameters => {
 249             additionalProperties => 0,
 250             properties => $update_properties,
 251         },
 252         returns => { type => 'null' },
 253         code => sub {
 254             my ($param) = @_;
 255
 256             my $rdb = PMG::RuleDB->new();
 257
 258             my $gid = $use_greylist_gid ?
 259                 $rdb->greylistexclusion_groupid() : $param->{ogroup};
 260
 261             my $obj = $rdb->load_object_full($param->{id}, $gid, $otype);
 262
 263             $obj->update($param);
 264
 265             $obj->save($rdb);
 266
 267             if ($use_greylist_gid) {
 268                 PMG::DBTools::reload_ruledb($rdb);
 269             } else {
 270                 PMG::DBTools::reload_ruledb();
 271             }
 272
 273             return undef;
 274         }});
 275
 276 }
 277
 278 1;
 279
 280 __END__
 281
 282 =head1 PMG::RuleDB::Object
 283
 284 The Proxmox Rules consists of Objects. There are several classes of Objects. Ech such class has a method to check if the object 'matches'.
 285
 286 =head2 WHO Objects ($obj->oclass() eq 'who')
 287
 288 Who sent the mail, who is the receiver?
 289
 290 =head3  $obj->who_match ($addr)
 291
 292 Returns true if $addr belongs to this objects. $addr is a text string representing the email address you want to check.
 293
 294 =over
 295
 296 =item *
 297
 298 EMail: the only attribute is a regex to test email addresses
 299
 300 =back
 301
 302 =head2 WHEN Objects ($obj->oclass() eq 'when')
 303
 304 Used to test for a certain daytime
 305
 306 =head3  $obj->when_match ($time)
 307
 308 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()).
 309
 310 =over
 311
 312 =item *
 313
 314 TimeFrame: specifies a start and a end time
 315
 316 =back
 317
 318 =head2 WHAT Objects ($obj->oclass() eq 'what')
 319
 320 mail content tests
 321
 322 =head2 ACTION Objects ($obj->oclass() eq 'action')
 323
 324 actions which can be executed
 325
 326 =head3 $obj->execute ($mod_group, $queue, $ruledb, $mod_group, $targets, $msginfo, $vars, $marks)
 327
 328 Execute the action code. $target is a array reference containing all
 329 matching targets.
 330
 331 =head2 Common Methods
 332
 333 =head3 $obj->oclass()
 334
 335 Returns 'who', 'when' 'what' or 'action';
 336
 337 =head3 $obj->short_desc()
 338
 339 Returns a short text describing the contents of the object. This is used
 340 for debugging purposes.
 341
 342 =head3 $obj->otype
 343
 344 Returns an integer representing the Type of the objects. This integer
 345 is used in the database to uniquely identify object types.
 346
 347 =head3 $obj->id
 348
 349 Returns the unique database ID of the object. undef means the object is not jet stored in the databse.
 350
 351 =head3 $obj->final()
 352
 353 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.
 354
 355 =head3 $obj->priority()
 356
 357 Return a priority between 0 and 100. This is currently used to sort action objects by priority.
 358