#!/usr/bin/ruby
# vim: set nosta noet ts=4 sw=4:
# A Ruby interface to a single Ezmlm-idx mailing list directory.
#
# list = Ezmlm::List.new( '/path/to/listdir' )
#
#
# == Version
#
# $Id$
#
#---
require 'pathname'
require 'time'
require 'etc'
require 'ezmlm' unless defined?( Ezmlm )
### A Ruby interface to an ezmlm-idx mailing list directory
###
class Ezmlm::List
# Valid subdirectories/sections for subscriptions.
SUBSCRIPTION_DIRS = %w[ deny mod digest allow ]
### Create a new Ezmlm::List object for the specified +listdir+, which should be
### an ezmlm-idx mailing list directory.
###
def initialize( listdir )
listdir = Pathname.new( listdir ) unless listdir.is_a?( Pathname )
unless listdir.directory? && ( listdir + 'mailinglist' ).exist?
raise ArgumentError, "%p doesn't appear to be an ezmlm-idx list." % [ listdir.to_s ]
end
@listdir = listdir
end
# The Pathname object for the list directory
attr_reader :listdir
### Return the configured name of the list (without the host)
###
def name
@name = self.read( 'outlocal' ) unless @name
return @name
end
### Return the configured host of the list
###
def host
@host = self.read( 'outhost' ) unless @host
return @host
end
### Return the configured address of the list (in list@host form)
###
def address
return "%s@%s" % [ self.name, self.host ]
end
alias_method :fullname, :address
### Return the email address of the list's owner.
###
def owner
owner = self.read( 'owner' )
return owner =~ /@/ ? owner : nil
end
### Returns +true+ if +address+ is a subscriber to this list.
###
def include?( addr, section: nil )
addr.downcase!
file = self.subscription_dir( section ) + Ezmlm::Hash.subscriber( addr )
return false unless file.exist?
return file.read.scan( /T([^\0]+)\0/ ).flatten.include?( addr )
end
alias_method :is_subscriber?, :include?
### Fetch a sorted Array of the email addresses for all of the list's
### subscribers.
###
def subscribers
return self.read_subscriber_dir
end
### Subscribe +addr+ to the list within +section+.
###
def subscribe( *addr, section: nil )
addr.each do |address|
next unless address.index( '@' )
address.downcase!
file = self.subscription_dir( section ) + Ezmlm::Hash.subscriber( address )
self.with_safety do
if file.exist?
addresses = file.read.scan( /T([^\0]+)\0/ ).flatten
addresses << address
file.open( 'w' ) do |f|
f.print addresses.uniq.sort.map{|a| "T#{a}\0" }.join
end
else
file.open( 'w' ) do |f|
f.print "T%s\0" % [ address ]
end
end
end
end
end
alias_method :add_subscriber, :subscribe
### Unsubscribe +addr+ from the list within +section+.
###
def unsubscribe( *addr, section: nil )
addr.each do |address|
address.downcase!
file = self.subscription_dir( section ) + Ezmlm::Hash.subscriber( address )
self.with_safety do
next unless file.exist?
addresses = file.read.scan( /T([^\0]+)\0/ ).flatten
addresses = addresses - [ address ]
if addresses.empty?
file.unlink
else
file.open( 'w' ) do |f|
f.print addresses.uniq.sort.map{|a| "T#{a}\0" }.join
end
end
end
end
end
alias_method :remove_subscriber, :unsubscribe
### Returns an Array of email addresses of people responsible for
### moderating subscription of a closed list.
###
def moderators
return self.read_subscriber_dir( 'mod' )
end
### Returns +true+ if +address+ is a moderator.
###
def is_moderator?( addr )
return self.include?( addr, section: 'mod' )
end
### Subscribe +addr+ to the list as a Moderator.
###
def add_moderator( *addr )
return self.subscribe( *addr, section: 'mod' )
end
### Remove +addr+ from the list as a Moderator.
###
def remove_moderator( *addr )
return self.unsubscribe( *addr, section: 'mod' )
end
### Returns an Array of email addresses denied access
### to the list.
###
def blacklisted
return self.read_subscriber_dir( 'deny' )
end
### Returns +true+ if +address+ is disallowed from participating.
###
def is_blacklisted?( addr )
return self.include?( addr, section: 'deny' )
end
### Blacklist +addr+ from the list.
###
def add_blacklisted( *addr )
return self.subscribe( *addr, section: 'deny' )
end
### Remove +addr+ from the blacklist.
###
def remove_blacklisted( *addr )
return self.unsubscribe( *addr, section: 'deny' )
end
### Returns an Array of email addresses that act like
### regular subscribers for user-post only lists.
###
def allowed
return self.read_subscriber_dir( 'allow' )
end
### Returns +true+ if +address+ is given the same benefits as a
### regular subscriber for user-post only lists.
###
def is_allowed?( addr )
return self.include?( addr, section: 'allow' )
end
### Add +addr+ to allow posting to user-post only lists,
### when +addr+ isn't a subscriber.
###
def add_allowed( *addr )
return self.subscribe( *addr, section: 'allow' )
end
### Remove +addr+ from the allowed list.
###
def remove_allowed( *addr )
return self.unsubscribe( *addr, section: 'allow' )
end
### Returns +true+ if the list is configured to respond
### to remote management requests.
###
def public?
return ( self.listdir + 'public' ).exist?
end
### Disable or enable remote management requests.
###
def public=( enable=true )
if enable
self.touch( 'public' )
else
self.unlink( 'public' )
end
end
alias_method :public, :public=
### Returns +true+ if the list is not configured to respond
### to remote management requests.
###
def private?
return ! self.public?
end
### Disable or enable remote management requests.
###
def private=( enable=false )
self.public = ! enable
end
alias_method :private, :private=
### Returns +true+ if the list supports remote administration
### subscribe/unsubscribe requests from moderators.
###
def remote_subscriptions?
return ( self.listdir + 'remote' ).exist?
end
### Disable or enable remote subscription requests.
###
def remote_subscriptions=( enable=false )
if enable
self.touch( 'remote' )
else
self.unlink( 'remote' )
end
end
alias_method :remote_subscriptions, :remote_subscriptions=
### Returns +true+ if list subscription requests require moderator
### approval.
###
def moderated_subscriptions?
return ( self.listdir + 'modsub' ).exist?
end
### Disable or enable subscription moderation.
###
def moderated_subscriptions=( enable=false )
if enable
self.touch( 'modsub' )
else
self.unlink( 'modsub' )
end
end
alias_method :moderated_subscriptions, :moderated_subscriptions=
### Returns +true+ if message moderation is enabled.
###
def moderated?
return ( self.listdir + 'modpost' ).exist?
end
### Disable or enable message moderation.
###
### This has special meaning when combined with user_posts_only setting.
### Lists act as unmoderated for subscribers, and posts from unknown
### addresses go to moderation.
###
def moderated=( enable=false )
if enable
self.touch( 'modpost' )
self.touch( 'noreturnposts' ) if self.user_posts_only?
else
self.unlink( 'modpost' )
self.unlink( 'noreturnposts' ) if self.user_posts_only?
end
end
alias_method :moderated, :moderated=
### Returns +true+ if posting is only allowed by moderators.
###
def moderator_posts_only?
return ( self.listdir + 'modpostonly' ).exist?
end
### Disable or enable moderation only posts.
###
def moderator_posts_only=( enable=false )
if enable
self.touch( 'modpostonly' )
else
self.unlink( 'modpostonly' )
end
end
alias_method :moderator_posts_only, :moderator_posts_only=
### Returns +true+ if posting is only allowed by subscribers.
###
def user_posts_only?
return ( self.listdir + 'subpostonly' ).exist?
end
### Disable or enable user only posts.
### This is easily defeated, moderated lists are preferred.
###
### This has special meaning for moderated lists. Lists act as
### unmoderated for subscribers, and posts from unknown addresses
### go to moderation.
###
def user_posts_only=( enable=false )
if enable
self.touch( 'subpostonly' )
self.touch( 'noreturnposts' )if self.moderated?
else
self.unlink( 'subpostonly' )
self.unlink( 'noreturnposts' ) if self.moderated?
end
end
alias_method :user_posts_only, :user_posts_only=
### Returns +true+ if message archival is enabled.
###
def archived?
test = %w[ archived indexed threaded ].each_with_object( [] ) do |f, acc|
acc << self.listdir + f
end
return test.all?( &:exist? )
end
### Disable or enable message archiving (and indexing/threading.)
###
def archived=( enable=true )
if enable
self.touch( 'archived', 'indexed', 'threaded' )
else
self.unlink( 'archived', 'indexed', 'threaded' )
end
end
alias_method :archived, :archived=
### Returns +true+ if the message archive is accessible only to
### moderators.
###
def private_archive?
return ( self.listdir + 'modgetonly' ).exist?
end
### Disable or enable private access to the archive.
###
def private_archive=( enable=true )
if enable
self.touch( 'modgetonly' )
else
self.unlink( 'modgetonly' )
end
end
alias_method :private_archive, :private_archive=
### Returns +true+ if the message archive is accessible to anyone.
###
def public_archive?
return ! self.private_archive?
end
### Disable or enable private access to the archive.
###
def public_archive=( enable=true )
self.private_archive = ! enable
end
alias_method :public_archive, :public_archive=
### Returns +true+ if the message archive is accessible only to
### list subscribers.
###
def guarded_archive?
return ( self.listdir + 'subgetonly' ).exist?
end
### Disable or enable loimited access to the archive.
###
def guarded_archive=( enable=true )
if enable
self.touch( 'subgetonly' )
else
self.unlink( 'subgetonly' )
end
end
alias_method :guarded_archive, :guarded_archive=
### Returns +true+ if message digests are enabled.
###
def digested?
return ( self.listdir + 'digested' ).exist?
end
### Disable or enable message digesting.
###
def digest=( enable=true )
if enable
self.touch( 'digested' )
else
self.unlink( 'digested' )
end
end
alias_method :digest, :digest=
### If the list is digestable, trigger the digest after this amount
### of message body since the latest digest, in kbytes.
###
### See: ezmlm-tstdig(1)
###
def digest_kbytesize
size = self.read( 'digsize' ).to_i
return size.zero? ? 64 : size
end
### If the list is digestable, trigger the digest after this amount
### of message body since the latest digest, in kbytes.
###
### See: ezmlm-tstdig(1)
###
def digest_kbytesize=( size=64 )
self.write( 'digsize' ) {|f| f.puts size.to_i }
end
### If the list is digestable, trigger the digest after this many
### messages have accumulated since the latest digest.
###
### See: ezmlm-tstdig(1)
###
def digest_count
count = self.read( 'digcount' ).to_i
return count.zero? ? 30 : count
end
### If the list is digestable, trigger the digest after this many
### messages have accumulated since the latest digest.
###
### See: ezmlm-tstdig(1)
###
def digest_count=( count=30 )
self.write( 'digcount' ) {|f| f.puts count.to_i }
end
### If the list is digestable, trigger the digest after this much
### time has passed since the last digest, in hours.
###
### See: ezmlm-tstdig(1)
###
def digest_timeout
hours = self.read( 'digtime' ).to_i
return hours.zero? ? 48 : hours
end
### If the list is digestable, trigger the digest after this much
### time has passed since the last digest, in hours.
###
### See: ezmlm-tstdig(1)
###
def digest_timeout=( hours=48 )
self.write( 'digtime' ) {|f| f.puts hours.to_i }
end
### Returns +true+ if the list requires subscriptions to be
### confirmed. AKA "help" mode if disabled.
###
def confirm_subscriptions?
return ! ( self.listdir + 'nosubconfirm' ).exist?
end
### Disable or enable subscription confirmation.
### AKA "help" mode if disabled.
###
def confirm_subscriptions=( enable=true )
if enable
self.unlink( 'nosubconfirm' )
else
self.touch( 'nosubconfirm' )
end
end
alias_method :confirm_subscriptions, :confirm_subscriptions=
### Returns +true+ if the list requires unsubscriptions to be
### confirmed. AKA "jump" mode.
###
def confirm_unsubscriptions?
return ! ( self.listdir + 'nounsubconfirm' ).exist?
end
### Disable or enable unsubscription confirmation.
### AKA "jump" mode.
###
def confirm_unsubscriptions=( enable=true )
if enable
self.unlink( 'nounsubconfirm' )
else
self.touch( 'nounsubconfirm' )
end
end
alias_method :confirm_unsubscriptions, :confirm_unsubscriptions=
### Returns +true+ if the list requires regular message postings
### to be confirmed by the original sender.
###
def confirm_postings?
return ( self.listdir + 'confirmpost' ).exist?
end
### Disable or enable message confirmation.
###
def confirm_postings=( enable=false )
if enable
self.touch( 'confirmpost' )
else
self.unlink( 'confirmpost' )
end
end
alias_method :confirm_postings, :confirm_postings=
### Returns +true+ if the list allows moderators to
### fetch a subscriber list remotely.
###
def allow_remote_listing?
return ( self.listdir + 'modcanlist' ).exist?
end
### Disable or enable the ability for moderators to
### remotely fetch a subscriber list.
###
def allow_remote_listing=( enable=false )
if enable
self.touch( 'modcanlist' )
else
self.unlink( 'modcanlist' )
end
end
alias_method :allow_remote_listing, :allow_remote_listing=
### Returns +true+ if the list automatically manages
### bouncing subscriber addresses.
###
def bounce_warnings?
return ! ( self.listdir + 'nowarn' ).exist?
end
### Disable or enable automatic bounce probes and warnings.
###
def bounce_warnings=( enable=true )
if enable
self.unlink( 'nowarn' )
else
self.touch( 'nowarn' )
end
end
alias_method :bounce_warnings, :bounce_warnings=
### Return the maximum message size, in bytes. Messages larger than
### this size will be rejected.
###
### See: ezmlm-reject(1)
###
def maximum_message_size
size = self.read( 'msgsize' )
return size ? size.split( ':' ).first.to_i : 0
end
### Set the maximum message size, in bytes. Messages larger than
### this size will be rejected. Defaults to 300kb.
###
### See: ezmlm-reject(1)
###
def maximum_message_size=( size=307200 )
if size.to_i.zero?
self.unlink( 'msgsize' )
else
self.write( 'msgsize' ) {|f| f.puts "#{size.to_i}:0" }
end
end
### Return the number of messages in the list archive.
###
def message_count
count = self.read( 'archnum' )
return count ? Integer( count ) : 0
end
### Returns an individual message if archiving was enabled.
###
def message( message_id )
raise "Message archive is empty." if self.message_count.zero?
return Ezmlm::List::Message.new( self, message_id ) rescue nil
end
### Lazy load each message ID as a Ezmlm::List::Message,
### yielding it to the block.
###
def each_message
( 1 .. self.message_count ).each do |id|
yield self.message( id )
end
end
### Return a Thread object for the given +thread_id+.
###
def thread( thread_id )
return Ezmlm::List::Thread.new( self, thread_id ) rescue nil
end
### Return an Author object for the given +author_id+, which
### could also be an email address.
###
def author( author_id )
author_id = Ezmlm::Hash.address(author_id) if author_id.index( '@' )
return Ezmlm::List::Author.new( self, author_id ) rescue nil
end
### Parse all thread indexes into a single array that can be used
### as a lookup table.
###
### These are not expanded into objects, use #message, #thread,
### and #author to do so.
###
def index
raise "Archiving is not enabled." unless self.archived?
archivedir = listdir + 'archive'
idx = ( 0 .. self.message_count / 100 ).each_with_object( [] ) do |dir, acc|
index = archivedir + dir.to_s + 'index'
next unless index.exist?
index.open( 'r', encoding: Encoding::ISO8859_1 ) do |fh|
fh.each_line.lazy.slice_before( /^\d+:/ ).each do |message|
match = message[0].match( /^(?<message_id>\d+): (?<thread_id>\w+)/ )
next unless match
thread_id = match[ :thread_id ]
match = message[1].match( /^(?<date>[^;]+);(?<author_id>\w+) / )
next unless match
author_id = match[ :author_id ]
date = match[ :date ]
metadata = {
date: Time.parse( date ),
thread: thread_id,
author: author_id
}
acc << metadata
end
end
end
return idx
end
#########
protected
#########
### Just return the contents of the provided +file+, rooted
### in the list directory.
###
def read( file )
file = self.listdir + file unless file.is_a?( Pathname )
return file.read.chomp
rescue
nil
end
### Overwrite +file+ safely, yielding the open filehandle to the
### block. Set the new file to correct ownership and permissions.
###
def write( file, &block )
file = self.listdir + file unless file.is_a?( Pathname )
self.with_safety do
file.open( 'w' ) do |f|
yield( f )
end
stat = self.listdir.stat
file.chown( stat.uid, stat.gid )
file.chmod( 0600 )
end
end
### Simply create an empty file, safely.
###
def touch( *file )
self.with_safety do
Array( file ).flatten.each do |f|
f = self.listdir + f unless f.is_a?( Pathname )
f.open( 'w' ) {}
end
end
end
### Delete +file+ safely.
###
def unlink( *file )
self.with_safety do
Array( file ).flatten.each do |f|
f = self.listdir + f unless f.is_a?( Pathname )
next unless f.exist?
f.unlink
end
end
end
### Return a Pathname to a subscription directory.
###
def subscription_dir( section=nil )
if section
unless SUBSCRIPTION_DIRS.include?( section )
raise "Invalid subscription dir: %s, must be one of: %s" % [
section,
SUBSCRIPTION_DIRS.join( ', ' )
]
end
return self.listdir + section + 'subscribers'
else
return self.listdir + 'subscribers'
end
end
### Read the hashed subscriber email addresses from the specified
### +directory+ and return them in an Array.
###
def read_subscriber_dir( section=nil )
directory = self.subscription_dir( section )
rval = []
Pathname.glob( directory + '*' ) do |hashfile|
rval.push( hashfile.read.scan(/T([^\0]+)\0/) )
end
return rval.flatten.sort
end
### Return a Pathname object for the list owner's home directory.
###
def homedir
user = Etc.getpwuid( self.listdir.stat.uid )
return Pathname( user.dir )
end
### Safely make modifications to a file within a list directory.
###
### Mail can come in at any time. Make changes within a list
### atomic -- if an incoming message hits when a sticky
### is set, it is deferred to the Qmail queue.
###
### - Set sticky bit on the list directory owner's homedir
### - Make changes with the block
### - Unset sticky (just back to what it was previously)
###
### All writes should be wrapped in this method.
###
def with_safety( &block )
home = self.homedir
mode = home.stat.mode
home.chmod( mode | 01000 ) # enable sticky
yield
ensure
home.chmod( mode )
end
end # class Ezmlm::List