slacklib.py

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

"""Snippets server -> Slack integration.

This provides HipChat integration with the snippet server, for
organizations that use Slack for messaging.  This provides Slack
integration with the snippet server, as well prototype CLI style
interaction with snippets via the Slack "slash commands" integration.

Talking to the Slack Web API requires a token.  The admin must enter
the value of this token on /admin/settings.  There are instructions
there for how to do so.

Additionally, the "slash commands" integration in Slack will post a
token with each request.  We check this token for security reasons, so
we get that from /admin/settings as well.
"""

import datetime
import json
import logging
import re
import os
import textwrap
import urllib
import urllib2
import webapp2

from google.appengine.ext import db
from google.appengine.api import memcache

import models
import util

# The Slack slash command token is sent to us by the Slack server with
# every incoming request.  We verify it here for security. To make it
# easier to develop, you can disable the verification step while
# testing.
_REQUIRE_SLASH_TOKEN = True


# This allows mocking in a different day, for testing.
_TODAY_FN = datetime.datetime.now

# The web URL we point people to as the base for web operations
_WEB_URL = 'http://' + os.environ.get('SERVER_NAME', 'localhost')


def _web_api(api_method, payload):
    """Send a payload to the Slack Web API, automatically inserting token.

    Uses AppSettings.slack_token to get the token.  Callers must ensure
    that slack_token exists (or this call will fail).

    Raises a ValueError if something goes wrong.
    Returns a dictionary with the response.
    """
    app_settings = models.AppSettings.get()
    payload.setdefault('token', app_settings.slack_token)
    uri = 'https://slack.com/api/' + api_method
    r = urllib2.urlopen(uri, urllib.urlencode(payload))

    # check return code for server errors
    if r.getcode() != 200:
        raise ValueError(r.read())
    # parse the JSON...
    # slack web API always returns either `"ok": true` or `"error": "reason"`
    reply = json.loads(r.read())
    if not reply['ok']:
        raise ValueError('Slack error: %s' % reply['error'])
    return reply


def _get_user_email(uid):
    """Retrieve the email address for a specific userid from the Slack Web API.

    Raises ValueError if could not be retrieved.
    """
    reply = _web_api('users.info', {'user': uid})  # possible ValueError
    email = reply.get('user', {}).get('profile', {}).get('email', None)
    if email is None:
        raise ValueError('Slack user profile did not have email')
    return email


def _get_user_email_cached(uid, force_refresh=False):
    """Retrieve the email address for a specific user id, with a cache.

    Results are stored in memcache for up to a day.

    If force_refresh parameter is specified, cached data will be refreshed.

    Raises ValueError if could not be retrieved.
    """
    key = 'slack_profile_email_' + uid
    cached_data = memcache.get(key)
    if (cached_data is None) or force_refresh:
        logging.debug("cache miss/refresh for slack email lookup %s", uid)
        email = _get_user_email(uid)  # possible ValueError
        if not memcache.set(key=key, value=email, time=86400):
            logging.error('memcache set failed!')
        return email
    else:
        logging.debug("cache hit for slack email lookup %s", uid)
        return cached_data


def send_to_slack_channel(channel, msg):
    """Send a plaintext message to a Slack channel."""
    try:
        _web_api('chat.postMessage', {
            'channel': channel,
            'text': msg,
            'username': 'Snippets',
            'icon_emoji': ':pencil:',
            'unfurl_links': False,    # no link previews, please
        })
    except ValueError, why:
        logging.error('Failed sending message to slack: %s', why)


###############################
### SLASH COMMANDS ARE FUN! ###
###############################

def command_usage():
    return textwrap.dedent("""
    /snippets                displays your current snippets
    /snippets list           displays your current snippets
    /snippets last           displays your snippets from last week
    /snippets add [item]     adds an item to your weekly snippets
    /snippets del [n]        removes snippet number N
    /snippets dump           shows your snippets list unformatted
    /snippets help           display this help screen
    """)


def command_help():
    """Return the help string for slash commands."""
    return (
        "I can help you manage your "
        "<{}|weekly snippets>! :pencil:".format(_WEB_URL) +
        command_usage()
    )


def _no_user_error(user_email):
    return (
        "You don't appear to have a snippets account yet!\n"
        "To create one, go to {}\n"
        "We looked for your Slack email address: {}"
        .format(_WEB_URL, user_email)
    )


def _user_snippet(user_email, weeks_back=0):
    """Return the user's most recent Snippet.

    If one doesn't exist, one will be automatically filled from the template
    (but not saved).

    By using the optional `weeks_back` parameter, you can step backwards in
    time. Note that if you go back before the user's *first* snippet, they will
    not be filled (the default filling seems to only go forwardwise in time),
    and an IndexError will be raised.

    Raises an IndexError if requested snippet week comes before user birth.
    Raises ValueError if user couldn't be found.
    """
    account = util.get_user_or_die(user_email)  # can raise ValueError
    user_snips = util.snippets_for_user(user_email)
    logging.debug(
        'User %s got snippets from db: %s', user_email, len(user_snips)
    )

    filled_snips = util.fill_in_missing_snippets(user_snips, account,
                                                 user_email, _TODAY_FN())
    logging.debug(
        'User %s snippets *filled* to: %s', user_email, len(filled_snips)
    )

    index = (-1) - weeks_back
    return filled_snips[index]


def _snippet_items(snippet):
    """Return a list of markdown items in the snippet text and any before/after residual.

    We find the first run of consecutive lines beginning with -*+, and extract those as items.

    Any text before the run begins, or text after the run ends, are preserved. This allows
    users to share additional content in their snippets besides a single ordered list. Slack
    won't allow edits to this prefix/suffix, but it won't lose or otherwise disturb it.

    Returns a 3-tuple: prefix, items, suffix. prefix/suffix may be empty, as may items.
    """
    unformatted = snippet.text and snippet.text.strip()

    # treat null text value as empty list
    if not unformatted:
        return '', [], ''

    prefix_lines = []
    items = []
    suffix_lines = []
    for line in unformatted.split('\n'):
        if suffix_lines:
            # We've already found and passed a consecutive run of list items
            suffix_lines.append(line)
            continue

        # A valid "item" is a line beginning with a markdown list item and a space
        is_item = len(line) > 2 and line[0] in '-*+' and line[1] == ' '
        if is_item:
            items.append(line[2:])
        else:
            if items:
                # This is the first line after our consecutive run of list items. Begin the suffix.
                suffix_lines = [line]
            else:
                # Haven't encountered a run of list items yet: just another random prefix line.
                prefix_lines.append(line)

    return '\n'.join(prefix_lines), items, '\n'.join(suffix_lines)


def _format_snippet_items(items):
    """Format snippet items for display."""
    fi = ['> :pushpin: *[{}]* {}'.format(i, x) for i, x in enumerate(items)]
    return "\n".join(fi)


def command_list(user_email):
    """Return the users current snippets for the week in pretty format."""
    try:
        snippet = _user_snippet(user_email)
        prefix, items, suffix = _snippet_items(snippet)
    except ValueError:
        return _no_user_error(user_email)

    if not snippet.text:
        return "*No snippet yet this week*. Try `/snippets add` to record an item. :rocket:"

    if not items:
        return (
            "*We found your snippet, but it doesn't have any listed items yet!* :speak_no_evil:\n"
            ":pencil: Use `/snippets add` to add an item. Here's what we have for you:\n"
            "```{}```".format(snippet.text)
        )

    return textwrap.dedent(
        "*Your snippet items for the week so far:*\n" +
        _format_snippet_items(items)
    )


def command_last(user_email):
    """Return the users snippets for last week in a pretty format."""
    try:
        snippet = _user_snippet(user_email, 1)
        prefix, items, suffix = _snippet_items(snippet)
    except ValueError:
        return _no_user_error(user_email)
    except IndexError:
        return "*You didn't have any snippets last week!* :speak_no_evil:"

    if not snippet.text:
        return "*You didn't have any snippets last week!* :speak_no_evil:"

    return "```{}```".format(snippet.text)


def _linkify_usernames(text):
    """Slack wants @usernames to be surrounded in <> to be highlighted."""
    return re.sub(r'(?<!<)(@[\w_]+)', r'<\1>', text)


def _markdown_list(items):
    """Transform a list of items into a markdown list."""
    return "\n".join(["- {}".format(x) for x in items])


def command_add(user_email, new_item):
    """Add a new item to the user's current snippet list."""
    if not new_item:
        return (
            ":grey_question: Urm, *what* do you want me to add exactly?\n"
            "Usage: `/snippets add [item]`"
        )

    # TODO(csilvers): move this get/update/put atomic into a txn
    try:
        snippet = _user_snippet(user_email)      # may raise ValueError
        prefix, items, suffix = _snippet_items(snippet)
    except ValueError:
        return _no_user_error(user_email)

    new_item = _linkify_usernames(new_item)
    items.append(new_item)
    snippet.text = prefix + "\n" + _markdown_list(items) + "\n" + suffix
    snippet.is_markdown = True

    # TODO(mroth): we should abstract out DB writes to a library wrapper
    db.put(snippet)
    db.get(snippet.key())    # ensure db consistency for HRD
    return "Added *{}* to your weekly snippets.".format(new_item)


def command_del(user_email, args):
    """Delete an item at an index from the users current snippets.

    The `args` parameter should be the args passed to the command.  We
    only expect one (for the index) but the user might not pass it, or pass
    extra things (which is an error condition for now).
    """
    syntax_err_msg = (
        ":grey_question: Urm, *what* do you want me to delete exactly?\n"
        "Usage: `/snippets del [n]`"
    )
    if not args or len(args) != 1:
        return syntax_err_msg

    try:
        index = int(args[0])
    except ValueError:
        return syntax_err_msg

    # TODO(csilvers): move this get/update/put atomic into a txn
    try:
        snippet = _user_snippet(user_email)      # may raise ValueError
        prefix, items, suffix = _snippet_items(snippet)
    except ValueError:
        return _no_user_error(user_email)

    try:
        removed_item = items[index]
        del items[index]
    except IndexError:
        return (
            ":grey_question: You don't have anything at that index?!\n" +
            _format_snippet_items(items)
        )

    snippet.text = prefix + "\n" + _markdown_list(items) + "\n" + suffix
    snippet.is_markdown = True

    db.put(snippet)
    db.get(snippet.key())    # ensure db consistency for HRD
    return "Removed *{}* from your weekly snippets.".format(removed_item)


def command_dump(user_email):
    """Return user's most recent snippet unformatted."""
    try:
        snippet = _user_snippet(user_email)
    except ValueError:
        return _no_user_error(user_email)
    return "```{}```".format(snippet.text or 'No snippet yet for this week')


class SlashCommand(webapp2.RequestHandler):
    def post(self):
        """Process an incoming slash command from Slack.

        Incoming request POST looks like the following (example taken from
        https://api.slack.com/slash-commands):
            token=gIkuvaNzQIHg97ATvDxqgjtO
            team_id=T0001
            team_domain=example
            channel_id=C2147483705
            channel_name=test
            user_id=U2147483697
            user_name=Steve
            command=/weather
            text=94070
        """
        req, res = self.request, self.response

        expected_token = models.AppSettings.get().slack_slash_token

        if not expected_token:
            res.write('Slack slash commands disabled. An admin '
                      'can enable them at /admin/settings')
            return

        # verify slash API post token for security
        if _REQUIRE_SLASH_TOKEN:
            token = req.get('token')
            if token != expected_token:
                logging.error("POST MADE WITH INVALID TOKEN")
                res.write("OH NO YOU DIDNT! Security issue plz contact admin.")
                return

        user_name = req.get('user_name')
        user_id = req.get('user_id')
        text = req.get('text')

        try:
            user_email = _get_user_email_cached(user_id)
        except ValueError:
            logging.error("Failed getting %s email from Slack API", user_name)
            res.write(
                "Error getting your email address from the Slack API! "
                "Please contact an admin and report the time of this error."
            )
            return

        words = text.strip().split()
        if not words:
            logging.info('null (list) command from user %s', user_name)
            res.write(command_list(user_email))
        else:
            cmd, args = words[0], words[1:]
            if cmd == 'help':
                logging.info('help command from user %s', user_name)
                res.write(command_help())
            elif cmd == 'whoami':
                # undocumented command to echo user email back
                logging.info('whoami command from user %s', user_name)
                res.write(user_email)
            elif cmd == 'whoami!':
                # whoami! forces a refresh of cache, for debugging
                logging.info('whoami! command from user %s', user_name)
                logging.info('whoami! potential cached email for %s: %s',
                             user_name, user_email)
                refreshed = _get_user_email_cached(user_id, force_refresh=True)
                logging.info('whoami! refreshed email for %s: %s',
                             user_name, refreshed)
                res.write(refreshed)
            elif cmd == 'list':
                # this is the same as the null command, but support for UX
                logging.info('list command from user %s', user_name)
                res.write(command_list(user_email))
            elif cmd == 'last':
                logging.info('last command from user %s', user_name)
                res.write(command_last(user_email))
            elif cmd == 'add':
                logging.info('add command from user %s', user_name)
                res.write(command_add(user_email, " ".join(args)))
            elif cmd == 'del':
                logging.info('del command from user %s', user_name)
                res.write(command_del(user_email, args))
            elif cmd == 'dump':
                logging.info('dump command from user %s', user_name)
                res.write(command_dump(user_email))
            else:
                logging.info('unknown command %s from user %s', cmd, user_name)
                res.write(
                    "I don't understand what you said! "
                    "Perhaps you meant one of these?\n```%s```\n"
                    % command_usage()
                )