Add a comment field to objects

Add a comment field to objects and corresponding commands to
wallet-backend and wallet to set and retrieve it.  The comment field
can only be set by the owner or wallet administrators but can be seen
by anyone on the show ACL.

3 files changed, 86 insertions, 11 deletions

diff --git a/perl/Wallet/Object/Base.pm b/perl/Wallet/Object/Base.pm
index 5097729..28ec6b9 100644
--- a/perl/Wallet/Object/Base.pm
+++ b/perl/Wallet/Object/Base.pm
@@ -1,7 +1,8 @@
 # Wallet::Object::Base -- Parent class for any object stored in the wallet.
 #
 # Written by Russ Allbery <rra@stanford.edu>
-# Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University
+# Copyright 2007, 2008, 2010, 2011
+#     The Board of Trustees of the Leland Stanford Junior University
 #
 # See LICENSE for licensing terms.
 
@@ -17,6 +18,7 @@ use vars qw($VERSION);
 
 use DBI;
 use POSIX qw(strftime);
+use Text::Wrap qw(wrap);
 use Wallet::ACL;
 
 # This version should be increased on any code change to this module.  Always
@@ -169,7 +171,7 @@ sub log_set {
     }
     my %fields = map { $_ => 1 }
         qw(owner acl_get acl_store acl_show acl_destroy acl_flags expires
-           flags type_data);
+           comment flags type_data);
     unless ($fields{$field}) {
         die "invalid history field $field";
     }
@@ -291,6 +293,19 @@ sub attr_show {
     return '';
 }
 
+# Get or set the comment value of an object.  If setting it, trace information
+# must also be provided.
+sub comment {
+    my ($self, $comment, $user, $host, $time) = @_;
+    if ($comment) {
+        return $self->_set_internal ('comment', $comment, $user, $host, $time);
+    } elsif (defined $comment) {
+        return $self->_set_internal ('comment', undef, $user, $host, $time);
+    } else {
+        return $self->_get_internal ('comment');
+    }
+}
+
 # Get or set the expires value of an object.  Expects an expiration time in
 # seconds since epoch.  If setting the expiration, trace information must also
 # be provided.
@@ -565,6 +580,7 @@ sub show {
                  [ ob_acl_destroy     => 'Destroy ACL'     ],
                  [ ob_acl_flags       => 'Flags ACL'       ],
                  [ ob_expires         => 'Expires'         ],
+                 [ ob_comment         => 'Comment'         ],
                  [ ob_created_by      => 'Created by'      ],
                  [ ob_created_from    => 'Created from'    ],
                  [ ob_created_on      => 'Created on'      ],
@@ -592,7 +608,14 @@ sub show {
 
     # Format the results.  We use a hack to insert the flags before the first
     # trace field since they're not a field in the object in their own right.
+    # The comment should be word-wrapped at 80 columns.
     for my $i (0 .. $#data) {
+        if ($attrs[$i][0] eq 'ob_comment' && length ($data[$i]) > 79 - 17) {
+            local $Text::Wrap::columns = 80;
+            local $Text::Wrap::unexpand = 0;
+            $data[$i] = wrap (' ' x 17, ' ' x 17, $data[$i]);
+            $data[$i] =~ s/^ {17}//;
+        }
         if ($attrs[$i][0] eq 'ob_created_by') {
             my @flags = $self->flag_list;
             if (not @flags and $self->error) {
@@ -778,6 +801,18 @@ attributes set, this method should return that metadata, formatted as key:
 value pairs with the keys right-aligned in the first 15 characters,
 followed by a space, a colon, and the value.
 
+=item comment([COMMENT, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves the comment associated with an object.  If no arguments
+are given, returns the current comment or undef if no comment is set.  If
+arguments are given, change the comment to COMMENT and return true on
+success and false on failure.  Pass in the empty string for COMMENT to
+clear the comment.
+
+The other arguments are used for logging and history and should indicate
+the user and host from which the change is made and the time of the
+change.
+
 =item destroy(PRINCIPAL, HOSTNAME [, DATETIME])
 
 Destroys the object by removing all record of it from the database.  The
diff --git a/perl/Wallet/Schema.pm b/perl/Wallet/Schema.pm
index 0f6c53f..7400776 100644
--- a/perl/Wallet/Schema.pm
+++ b/perl/Wallet/Schema.pm
@@ -145,7 +145,9 @@ sub upgrade {
         return;
     } elsif ($version == 0) {
         @sql = ('create table metadata (md_version integer)',
-                   'insert into metadata (md_version) values (1)');
+                'insert into metadata (md_version) values (1)',
+                'alter table objects add ob_comment varchar(255) default null'
+               );
     } else {
         die "unknown database version $version\n";
     }
@@ -367,6 +369,7 @@ table:
       ob_downloaded_by    varchar(255) default null,
       ob_downloaded_from  varchar(255) default null,
       ob_downloaded_on    datetime default null,
+      ob_comment          varchar(255) default null,
       primary key (ob_name, ob_type));
   create index ob_owner on objects (ob_owner);
   create index ob_expires on objects (ob_expires);
diff --git a/perl/Wallet/Server.pm b/perl/Wallet/Server.pm
index 185bf23..7b3fb8f 100644
--- a/perl/Wallet/Server.pm
+++ b/perl/Wallet/Server.pm
@@ -1,7 +1,8 @@
 # Wallet::Server -- Wallet system server implementation.
 #
 # Written by Russ Allbery <rra@stanford.edu>
-# Copyright 2007, 2008, 2010 Board of Trustees, Leland Stanford Jr. University
+# Copyright 2007, 2008, 2010, 2011
+#     The Board of Trustees of the Leland Stanford Junior University
 #
 # See LICENSE for licensing terms.
 
@@ -23,7 +24,7 @@ use Wallet::Schema;
 # This version should be increased on any code change to this module.  Always
 # use two digits for the minor version with a leading zero if necessary so
 # that it will sort properly.
-$VERSION = '0.09';
+$VERSION = '0.10';
 
 ##############################################################################
 # Utility methods
@@ -276,7 +277,9 @@ sub object_error {
 # set the ACL accordingly.
 sub acl_check {
     my ($self, $object, $action) = @_;
-    unless ($action =~ /^(get|store|show|destroy|flags|setattr|getattr)\z/) {
+    my %actions = map { $_ => 1 }
+        qw(get store show destroy flags setattr getattr comment);
+    unless ($actions{$action}) {
         $self->error ("unknown action $action");
         return;
     }
@@ -288,10 +291,10 @@ sub acl_check {
         $id = $object->acl ('show');
     } elsif ($action eq 'setattr') {
         $id = $object->acl ('store');
-    } else {
+    } elsif ($action ne 'comment') {
         $id = $object->acl ($action);
     }
-    if (! defined ($id) and $action =~ /^(get|(get|set)attr|store|show)\z/) {
+    if (! defined ($id) and $action ne 'flags' and $action ne 'destroy') {
         $id = $object->owner;
     }
     unless (defined $id) {
@@ -365,6 +368,26 @@ sub attr {
     }
 }
 
+# Retrieves or sets the comment of an object.
+sub comment {
+    my ($self, $type, $name, $comment) = @_;
+    undef $self->{error};
+    my $object = $self->retrieve ($type, $name);
+    return unless defined $object;
+    my $result;
+    if (defined $comment) {
+        return unless $self->acl_check ($object, 'comment');
+        $result = $object->comment ($comment, $self->{user}, $self->{host});
+    } else {
+        return unless $self->acl_check ($object, 'show');
+        $result = $object->comment;
+    }
+    if (not defined ($result) and $object->error) {
+        $self->error ($object->error);
+    }
+    return $result;
+}
+
 # Retrieves or sets the expiration of an object.
 sub expires {
     my ($self, $type, $name, $expires) = @_;
@@ -895,6 +918,20 @@ Check whether an object of type TYPE and name NAME exists.  Returns 1 if
 it does, 0 if it doesn't, and undef if some error occurred while checking
 for the existence of the object.
 
+=item comment(TYPE, NAME, [COMMENT])
+
+Gets or sets the comment for the object identified by TYPE and NAME.  If
+COMMENT is not given, returns the current comment or undef if no comment
+is set or on an error.  To distinguish between an expiration that isn't
+set and a failure to retrieve the expiration, the caller should call
+error() after an undef return.  If error() also returns undef, no comment
+was set; otherwise, error() will return the error message.
+
+If COMMENT is given, sets the comment to COMMENT.  Pass in the empty
+string for COMMENT to clear the comment.  To set a comment, the current
+user must be the object owner or be on the ADMIN ACL.  Returns true for
+success and false for failure.
+
 =item create(TYPE, NAME)
 
 Creates a new object of type TYPE and name NAME.  TYPE must be a
@@ -933,12 +970,12 @@ Gets or sets the expiration for the object identified by TYPE and NAME.
 If EXPIRES is not given, returns the current expiration or undef if no
 expiration is set or on an error.  To distinguish between an expiration
 that isn't set and a failure to retrieve the expiration, the caller should
-call error() after an undef return.  If error() also returns undef, that
-ACL wasn't set; otherwise, error() will return the error message.
+call error() after an undef return.  If error() also returns undef, the
+expiration wasn't set; otherwise, error() will return the error message.
 
 If EXPIRES is given, sets the expiration to EXPIRES.  EXPIRES must be in
 the format C<YYYY-MM-DD +HH:MM:SS>, although the time portion may be
-omitted.  Pass in the empty +string for EXPIRES to clear the expiration
+omitted.  Pass in the empty string for EXPIRES to clear the expiration
 date.  To set an expiration, the current user must be authorized by the
 ADMIN ACL.  Returns true for success and false for failure.