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