pocket_phone 0.1.0

data/lib/pocket_phone/carrier.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module PocketPhone
+  # Moves messages between the app and the phones, after the request that
+  # created them has been answered.
+  module Carrier
+    TAPBACK_VERBS = {
+      "love" => "Loved", "like" => "Liked", "dislike" => "Disliked",
+      "laugh" => "Laughed at", "emphasize" => "Emphasized", "question" => "Questioned"
+    }.freeze
+    # Sendblue's code for a message that was accepted and then failed to send.
+    SEND_FAILED = 10_001
+
+    module_function
+
+    # A message the app sent: walk it through Sendblue's statuses, telling the
+    # app about each one through its status callback and outbound webhook.
+    def deliver_to_phone(handle)
+      Runner.run do
+        outcome = PocketPhone.store.read.message(handle)&.dig("outcome")
+        steps = outcome == "failed" ? %w[ERROR] : %w[SENT DELIVERED]
+        steps.each do |status|
+          Runner.pause(PocketPhone.config.delivery_delay)
+          break unless advance(handle, status)
+        end
+      end
+    end
+
+    # A message a phone sent: the receive webhook.
+    def deliver_to_app(handle)
+      Runner.run do
+        database = PocketPhone.store.read
+        message = database.message(handle) or next
+        conversation = database.conversations[message["conversation_id"]] or next
+        result = receive(Payloads.message(message, conversation))
+        PocketPhone.store.write { |db| db.log_webhook(handle, result) }
+      end
+    end
+
+    # A tapback made on the phone, on something the app sent. Sendblue
+    # documents no webhook shape for these, so by default it travels as the
+    # text an iPhone falls back to: Loved “hello”.
+    def reaction_to_app(handle, by:, reaction:)
+      return unless PocketPhone.config.inbound_reactions == :text
+
+      Runner.run do
+        database = PocketPhone.store.read
+        target = database.message(handle) or next
+        conversation = database.conversations[target["conversation_id"]] or next
+        tapback = { "handle" => SecureRandom.uuid.upcase, "direction" => "phone", "status" => "RECEIVED",
+                    "from_number" => by, "to_number" => conversation["line"],
+                    "content" => reaction_text(target, reaction), "service" => target["service"],
+                    "created_at" => PocketPhone.now, "updated_at" => PocketPhone.now }
+        result = receive(Payloads.message(tapback, conversation)).merge("type" => "reaction")
+        PocketPhone.store.write { |db| db.log_webhook(handle, result) }
+      end
+    end
+
+    def typing_to_app(conversation, is_typing:)
+      Runner.run do
+        url = Runner.with_app { PocketPhone.config.typing_webhook_url } or next
+        Webhook.deliver(type: "typing_indicator", url: url,
+          payload: Payloads.typing(number: conversation["number"], line: conversation["line"], is_typing: is_typing))
+      end
+    end
+
+    # Look up the card for a link, the way the sending phone does. Fetched
+    # fresh for every message, since the page you are previewing is likely the
+    # one you are editing.
+    def fetch_preview(handle)
+      return unless PocketPhone.config.link_previews
+
+      message = PocketPhone.store.read.message(handle) or return
+      url = LinkPreview.detect(message["content"])[:url] or return
+      Runner.run do
+        preview = LinkPreview.fetch(url)
+        PocketPhone.store.write { |db| db.previews[url] = preview }
+      end
+    end
+
+    def reaction_text(target, reaction)
+      quoted = target["content"].to_s.empty? ? "an attachment" : "“#{target["content"]}”"
+      verb = TAPBACK_VERBS[reaction]
+      verb ? "#{verb} #{quoted}" : "Reacted #{reaction} to #{quoted}"
+    end
+
+    # --- internals ----------------------------------------------------------
+
+    def advance(handle, status)
+      payload, callback = PocketPhone.store.write do |db|
+        message = db.message(handle) or next
+        conversation = db.conversations[message["conversation_id"]] or next
+        message["status"] = status
+        message["updated_at"] = PocketPhone.now
+        if status == "ERROR"
+          message["error_code"] = SEND_FAILED
+          message["error_message"] = "Message failed to send (simulated by pocket_phone)"
+          conversation["unread"] = [conversation["unread"].to_i - 1, 0].max
+        end
+        [Payloads.message(message, conversation), message["status_callback"]]
+      end
+      return false unless payload
+
+      outbound = Runner.with_app { PocketPhone.config.outbound_webhook_url }
+      [callback, outbound].compact.uniq.each do |url|
+        result = Webhook.deliver(type: "outbound #{status}", url: url, payload: payload)
+        PocketPhone.store.write { |db| db.log_webhook(handle, result) }
+      end
+      true
+    end
+
+    def receive(payload)
+      url = Runner.with_app { PocketPhone.config.webhook_url }
+      return Webhook.record("receive", "", "error" => "no webhook_url configured") unless url
+
+      Webhook.deliver(type: "receive", url: url, payload: payload)
+    end
+  end
+end

data/lib/pocket_phone/configuration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PocketPhone
+  class Configuration
+    # Settings that may be given as a value or as a callable. A callable is
+    # resolved each time it is read, so it can lean on app code that is not
+    # loaded yet when the initializer runs (a credentials row, say).
+    LAZY = %i[
+      storage_path webhook_url outbound_webhook_url typing_webhook_url
+      signing_secret secret_header from_number account_email api_key_id api_secret
+    ].freeze
+
+    attr_writer(*LAZY)
+
+    # Deliver webhooks and fetch link previews on a background thread. Turn off
+    # in tests to make everything happen inline, with no delays.
+    attr_accessor :async
+    # Seconds between the QUEUED, SENT and DELIVERED steps of a message the app
+    # sends.
+    attr_accessor :delivery_delay
+    # Fetch og: tags for links, the way iMessage does.
+    attr_accessor :link_previews
+    # How a tapback made on the phone reaches the app: :text sends it as a
+    # received message ("Loved “hello”"), :none keeps it in the UI only.
+    attr_accessor :inbound_reactions
+    # Seconds to wait for the app to answer a webhook.
+    attr_accessor :webhook_timeout
+    # People to create on first use: [{ name: "Alice", number: "+15555550101",
+    # service: "iMessage" }]
+    attr_accessor :people
+
+    def initialize
+      @secret_header = "sb-signing-secret"
+      @account_email = "pocket_phone@example.com"
+      @async = true
+      @delivery_delay = 0.4
+      @link_previews = true
+      @inbound_reactions = :text
+      @webhook_timeout = 45
+      @people = []
+    end
+
+    LAZY.each do |name|
+      define_method(name) do
+        value = instance_variable_get(:"@#{name}")
+        value = value.call if value.respond_to?(:call)
+        value.respond_to?(:empty?) && value.empty? ? nil : value
+      end
+    end
+
+    def storage_path
+      value = @storage_path
+      value = value.call if value.respond_to?(:call)
+      return value.to_s if value
+
+      root = defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.to_s : Dir.pwd
+      File.join(root, "tmp", "pocket_phone")
+    end
+  end
+end

data/lib/pocket_phone/database.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module PocketPhone
+  # Everything pocket_phone knows, as one plain hash that round-trips through
+  # JSON: the app's lines, the fake people, their conversations and messages.
+  class Database
+    SERVICES = %w[iMessage SMS RCS].freeze
+    # What happens to a message the app sends this person: it arrives, it
+    # fails after being accepted, or the send is refused outright.
+    OUTCOMES = %w[delivered failed rejected].freeze
+
+    attr_reader :data
+
+    def self.blank
+      { "version" => 0, "lines" => {}, "people" => {}, "conversations" => {},
+        "messages" => {}, "previews" => {} }
+    end
+
+    def initialize(data)
+      @data = self.class.blank.merge(data || {})
+    end
+
+    def version = data["version"].to_i
+    def lines = data["lines"]
+    def people = data["people"]
+    def conversations = data["conversations"]
+    def messages = data["messages"]
+    def previews = data["previews"]
+
+    # --- lines and people ---------------------------------------------------
+
+    def ensure_line(number)
+      lines[number] ||= { "number" => number }
+    end
+
+    def ensure_person(number, attrs = {})
+      person = people[number] ||= { "number" => number, "name" => nil,
+                                    "service" => "iMessage", "outcome" => "delivered" }
+      attrs.each do |key, value|
+        next if value.nil? || value.to_s.empty?
+
+        person[key.to_s] = value.to_s
+      end
+      person["service"] = "iMessage" unless SERVICES.include?(person["service"])
+      person["outcome"] = "delivered" unless OUTCOMES.include?(person["outcome"])
+      person
+    end
+
+    # --- conversations ------------------------------------------------------
+
+    def direct(line, number, create: true)
+      id = "dm_#{Digest::SHA1.hexdigest("#{line}|#{number}")[0, 16]}"
+      return conversations[id] unless create
+
+      conversations[id] ||= { "id" => id, "kind" => "direct", "line" => line, "number" => number,
+                              "unread" => 0, "updated_at" => PocketPhone.now }
+    end
+
+    # The one-to-one this number is in, whichever line it is with. For calls
+    # that name the person but not the line.
+    def latest_direct(number)
+      conversations.values
+        .select { |c| c["kind"] == "direct" && c["number"] == number }
+        .max_by { |c| c["updated_at"].to_s }
+    end
+
+    def group(group_id)
+      conversation = conversations[group_id]
+      conversation if conversation && conversation["kind"] == "group"
+    end
+
+    def create_group(line:, participants:, name: nil, group_id: nil)
+      id = group_id.to_s.empty? ? SecureRandom.uuid : group_id.to_s
+      participants.each { |number| ensure_person(number) }
+      conversations[id] = { "id" => id, "kind" => "group", "line" => line, "group_id" => id,
+                            "participants" => participants.uniq, "name" => name.to_s.empty? ? nil : name,
+                            "unread" => 0, "updated_at" => PocketPhone.now }
+    end
+
+    def sorted_conversations
+      conversations.values.sort_by { |c| c["updated_at"].to_s }.reverse
+    end
+
+    def group?(conversation) = conversation["kind"] == "group"
+
+    # A group is only blue when everyone in it is; one Android phone turns the
+    # whole thread into group MMS.
+    def service_for(conversation)
+      if group?(conversation)
+        blue = conversation["participants"].all? { |n| people.dig(n, "service").to_s == "iMessage" }
+        blue ? "iMessage" : "SMS"
+      else
+        people.dig(conversation["number"], "service") || "iMessage"
+      end
+    end
+
+    def typing?(conversation)
+      conversation && conversation["typing_until"].to_s > PocketPhone.now &&
+        service_for(conversation) == "iMessage"
+    end
+
+    def delete_conversation(id)
+      conversations.delete(id)
+      messages.delete_if { |_, message| message["conversation_id"] == id }
+    end
+
+    # --- messages -----------------------------------------------------------
+
+    def message(handle) = messages[handle.to_s]
+
+    def messages_for(conversation)
+      messages.values.select { |m| m["conversation_id"] == conversation["id"] }
+    end
+
+    def add_message(conversation, attrs)
+      now = PocketPhone.now
+      attrs = attrs.transform_keys(&:to_s).compact
+      from_app = attrs["direction"] == "app"
+      message = {
+        # Sendblue's own handles look like this: lower case for what you sent,
+        # upper case for what a phone sent you.
+        "handle" => from_app ? SecureRandom.uuid : SecureRandom.uuid.upcase,
+        "conversation_id" => conversation["id"], "created_at" => now, "updated_at" => now,
+        "reactions" => [], "webhooks" => []
+      }.merge(attrs)
+      messages[message["handle"]] = message
+
+      conversation["updated_at"] = now
+      if from_app
+        # The message is the answer the dots were promising.
+        conversation.delete("typing_until")
+        conversation["unread"] = conversation["unread"].to_i + 1 unless message["status"] == "ERROR"
+      end
+      message
+    end
+
+    # One reaction per sender per message, as in iMessage. Returns :added or
+    # :removed.
+    def react(message, by:, reaction:, remove: false)
+      list = message["reactions"] ||= []
+      existing = list.find { |r| r["by"] == by }
+      list.delete(existing) if existing
+      return :removed if remove || (existing && existing["reaction"] == reaction)
+
+      list << { "by" => by, "reaction" => reaction }
+      :added
+    end
+
+    def log_webhook(handle, result)
+      found = message(handle) or return
+      (found["webhooks"] ||= []) << result
+    end
+  end
+end

data/lib/pocket_phone/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module PocketPhone
+  class Engine < ::Rails::Engine
+    isolate_namespace PocketPhone
+  end
+end

data/lib/pocket_phone/link_preview.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "net/http"
+require "nokogiri"
+require "uri"
+
+module PocketPhone
+  # The rich link card iMessage draws for a URL, and the rules for when it
+  # draws one.
+  module LinkPreview
+    URL = %r{https?://[^\s<>"]+}i
+    # Punctuation that ends a sentence rather than a URL. iMessage does not
+    # expand a link that is touching any of it.
+    TRAILING = /[.,;:!?'")\]}>]+\z/
+    # What Messages sends when it fetches a page. Sites that serve og: tags
+    # only to crawlers key on the facebookexternalhit / Twitterbot part.
+    USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/601.2.4 " \
+                 "(KHTML, like Gecko) Version/9.0.1 Safari/601.2.4 " \
+                 "facebookexternalhit/1.1 Facebot Twitterbot/1.0"
+    MAX_BYTES = 1_000_000
+    MAX_REDIRECTS = 5
+
+    SINGLE = "iMessage only previews a message with a single link"
+    EDGE = "iMessage only previews a link at the very start or end of a message, " \
+           "not mid-sentence or touching punctuation"
+
+    module_function
+
+    # Which link in this text iMessage would expand, if any, and why not when
+    # it would not: { url:, reason: }. A message with no links has neither.
+    def detect(text)
+      text = text.to_s.strip
+      urls = text.scan(URL).map { |url| url.sub(TRAILING, "") }
+      return { url: nil, reason: nil } if urls.empty?
+      return { url: nil, reason: SINGLE } if urls.size > 1
+
+      url = urls.first
+      at_start = text.start_with?(url) && text[url.length].to_s.match?(/\A(\s|\z)/)
+      at_end = text.end_with?(url) && (text.length == url.length || text[-url.length - 1].match?(/\s/))
+      at_start || at_end ? { url: url, reason: nil } : { url: nil, reason: EDGE }
+    end
+
+    # Fetch the page and read its og: tags. Never raises: a page that cannot
+    # be read comes back with "error" set.
+    def fetch(url)
+      uri, response = get(url)
+      type = response["content-type"].to_s
+      preview = base(url, uri)
+      if type.start_with?("image/")
+        preview.merge("image" => uri.to_s)
+      elsif type.include?("html") || type.empty?
+        preview.merge(parse(response.body.to_s.byteslice(0, MAX_BYTES), uri))
+      else
+        preview.merge("title" => File.basename(uri.path))
+      end
+    rescue StandardError => e
+      base(url, nil).merge("error" => "#{e.class.name}: #{e.message}")
+    end
+
+    def parse(html, uri)
+      document = Nokogiri::HTML(html)
+      meta = lambda do |*names|
+        names.each do |name|
+          node = document.at_css(%(meta[property="#{name}"], meta[name="#{name}"]))
+          value = node && node["content"].to_s.strip
+          return value unless value.nil? || value.empty?
+        end
+        nil
+      end
+      icon = document.at_css('link[rel="apple-touch-icon"], link[rel~="icon"]')
+
+      {
+        "title" => meta.call("og:title", "twitter:title") || document.at_css("title")&.text&.strip,
+        "description" => meta.call("og:description", "twitter:description", "description"),
+        "site_name" => meta.call("og:site_name"),
+        "image" => resolve(uri, meta.call("og:image:secure_url", "og:image", "twitter:image")),
+        "icon" => resolve(uri, icon && icon["href"])
+      }.compact
+    end
+
+    # A page the real thing could never show: Apple's fetch happens on a
+    # phone, and a phone cannot reach your laptop's localhost.
+    def local?(host)
+      host = host.to_s.downcase.delete_prefix("[").delete_suffix("]")
+      return true if host == "localhost" || host.end_with?(".localhost", ".local", ".test", ".internal")
+
+      address = IPAddr.new(host)
+      address.loopback? || address.private? || address.link_local?
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def get(url, redirects = MAX_REDIRECTS)
+      uri = URI.parse(url)
+      raise ArgumentError, "not an http(s) URL" unless uri.is_a?(URI::HTTP) && uri.host
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+        open_timeout: 3, read_timeout: 5) do |http|
+        http.get(uri.request_uri, "User-Agent" => USER_AGENT, "Accept" => "text/html,*/*")
+      end
+      if response.is_a?(Net::HTTPRedirection) && response["location"]
+        raise "too many redirects" if redirects.zero?
+
+        return get(URI.join(uri, response["location"]).to_s, redirects - 1)
+      end
+      raise "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      [uri, response]
+    end
+
+    def base(url, uri)
+      host = (uri || URI.parse(url)).host.to_s
+      { "url" => url, "host" => host.delete_prefix("www."), "local" => local?(host),
+        "fetched_at" => PocketPhone.now }
+    rescue URI::InvalidURIError
+      { "url" => url, "host" => "", "local" => false, "fetched_at" => PocketPhone.now }
+    end
+
+    def resolve(uri, href)
+      return nil if href.nil? || href.empty?
+
+      URI.join(uri, href).to_s
+    rescue URI::Error
+      nil
+    end
+  end
+end

data/lib/pocket_phone/numbers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PocketPhone
+  module Numbers
+    E164 = /\A\+[1-9]\d{6,14}\z/
+    EMAIL = /\A[^@\s]+@[^@\s]+\z/
+
+    module_function
+
+    # What the UI accepts: anything a person might type. "555 123 4567" becomes
+    # +15551234567; an iMessage email address is kept as it is.
+    def normalize(value)
+      text = value.to_s.strip
+      return text.downcase if text.include?("@")
+
+      digits = text.gsub(/\D/, "")
+      return "" if digits.empty?
+      return "+#{digits}" if text.start_with?("+")
+
+      digits.length == 10 ? "+1#{digits}" : "+#{digits}"
+    end
+
+    # What the API accepts: Sendblue takes E.164 (or an email) and nothing else.
+    def valid?(value)
+      text = value.to_s
+      text.match?(E164) || text.match?(EMAIL)
+    end
+
+    def pretty(number)
+      text = number.to_s
+      match = text.match(/\A\+1(\d{3})(\d{3})(\d{4})\z/)
+      match ? "+1 (#{match[1]}) #{match[2]}-#{match[3]}" : text
+    end
+
+    # A number nobody owns, for the "new person" form.
+    def random
+      format("+1555555%04d", rand(100..9999))
+    end
+  end
+end

data/lib/pocket_phone/payloads.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PocketPhone
+  # The JSON Sendblue uses to describe a message: the same shape answers a
+  # send, arrives in a status callback and arrives in the receive webhook.
+  module Payloads
+    module_function
+
+    def message(message, conversation)
+      from_app = message["direction"] == "app"
+      group = conversation["kind"] == "group"
+      counterpart = from_app ? message["to_number"] : message["from_number"]
+
+      {
+        "accountEmail" => PocketPhone.config.account_email,
+        "content" => message["content"].to_s,
+        "is_outbound" => from_app,
+        "status" => message["status"],
+        "error_code" => message["error_code"],
+        "error_message" => message["error_message"],
+        "error_detail" => nil,
+        "message_handle" => message["handle"],
+        "date_sent" => message["created_at"],
+        "date_updated" => message["updated_at"],
+        "from_number" => message["from_number"].to_s,
+        "number" => counterpart.to_s,
+        "to_number" => message["to_number"].to_s,
+        "sendblue_number" => conversation["line"],
+        "was_downgraded" => from_app ? message["service"] != "iMessage" : nil,
+        "plan" => "blue",
+        "media_url" => message["media_url"].to_s,
+        "message_type" => group ? "group" : "message",
+        "group_id" => group ? conversation["group_id"] : "",
+        "group_display_name" => group ? conversation["name"] : nil,
+        "participants" => group ? conversation["participants"] : [],
+        "send_style" => message["send_style"].to_s,
+        "opted_out" => false,
+        "service" => message["service"]
+      }.tap do |payload|
+        payload["media_urls"] = message["media_urls"] if message["media_urls"]
+        payload["app_card"] = message["app_card"] if message["app_card"]
+      end
+    end
+
+    def typing(number:, line:, is_typing:)
+      { "number" => number, "is_typing" => is_typing, "from_number" => line,
+        "timestamp" => PocketPhone.now }
+    end
+  end
+end

data/lib/pocket_phone/runner.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PocketPhone
+  # Where work that must not hold up a request goes. Sendblue answers a send
+  # straight away and reports what happened later; so does this.
+  module Runner
+    module_function
+
+    def run(&block)
+      return block.call unless PocketPhone.config.async
+
+      Thread.new do
+        block.call
+      rescue StandardError => e
+        log("#{e.class}: #{e.message}")
+      end
+    end
+
+    def pause(seconds)
+      sleep(seconds) if PocketPhone.config.async && seconds.to_f.positive?
+    end
+
+    # For the moments a background thread touches the host app's code (a
+    # configured lambda reading a model). Kept short on purpose: the thread
+    # must not be inside the executor while it calls the app over HTTP, or a
+    # code reload waiting on it would wait on itself.
+    def with_app(&block)
+      app = defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+      app ? app.executor.wrap(&block) : block.call
+    end
+
+    def log(message)
+      logger = defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+      logger&.warn("[pocket_phone] #{message}")
+    end
+  end
+end