crest 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75faee574d6193d7dedbaf585f4260b503bfc0c773af9313669ba76bc4c2a7a9
-  data.tar.gz: 04e8c9160ca452c308deed21f9a5aad900068a9547f7149eae597c3336084b4b
+  metadata.gz: dbe18f619bc95f0eb929c699184702b55f595cdd81f2287a8ef964e0b121b3dd
+  data.tar.gz: ee2f37cc8c25e057db03c6c3f7cb92d68164e278427cea28ac44dd733228ee8e
 SHA512:
-  metadata.gz: 482847bd72627b7016f551f46a3e89eac352bee26b9e4586322d90276dc3d95f47d82c2380743fbe1394f8e606b58812a55d622056fec278205d5e432875a531
-  data.tar.gz: 8ae58bf911147b1829be723453dfed043db427539e498d7c0d8a5a6f65ee0e319f4d5f217ae97b3f096159b323b125fd8cbebe00d5b0e5c29ca50bc829648fbe
+  metadata.gz: a2fc6523bd91f1d421ffe6806f9d4a30ae4bcd280b75e76aa35719db24bb9f7d51c054b99e227816815363b8969721bddda64619b96406a9e5bf877d7a43d453
+  data.tar.gz: '06169a97517d48d394d24b6b578e1424bddb2c52e3c6b11cef6c81bb46a2dff9e1e22d6fdabfc970f2bb40ad6cd82fc255b1e5b5b1d49f7a1d9d762173e39c42'

data/CHANGELOG.md

@@ -7,6 +7,22 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 1.0.0 - 2026-09-11
+
+* [Breaking change] Answer `Crest::Photo#property` where `#to_s` used to answer, and leave a
+  picture that is neither a PNG nor a JPEG off the card -- warned about on stderr, which a host
+  already collects -- rather than raising. A card without a picture beats a 500 on a route
+  that is public by definition, and a `to_s` that can answer nil is a trap for anyone
+  interpolating one
+* [Breaking change] Drop `Crest::Photo.of` and the process-wide hash of pictures behind it, so
+  `Crest::Card` builds a `Crest::Photo` and the gem holds no mutable global state at all. It saved
+  one file read and one base64 of a few kilobytes on a route hit occasionally, and charged for it
+  with a hash keyed on whatever was handed in -- the image bytes themselves, where a host passes
+  bytes -- never evicted, growing without bound for any host whose `photo` callable resolves to
+  more than one picture, and blind to a file that changed on disk
+* [Feature] Say that the card is an organization's: `N:` carries the one name a business has,
+  which is what makes `name` a single setting rather than a compromise
+
 ## 0.1.1 - 2026-09-11
 
 * [Fix] Name HouseAccount, Inc. as the copyright holder in the license, which 0.1.0 shipped

data/README.md

@@ -3,7 +3,7 @@
 A contact card your Rails app hands out, so a text from an unknown number arrives under a name.
 
 `GET /houseaccount.vcf` answers with a vCard. A phone offers to save it, and from then on your
-messages come from *HouseAccount* rather than from `+1 800 555 0100`.
+messages come from *HouseAccount* rather than from `774-468-7322`.
 
 ## How to install
 
@@ -14,12 +14,12 @@ gem install crest
 Or, in your `Gemfile`:
 
 ```ruby
-gem 'crest', '~> 0.1.0'
+gem 'crest', '~> 1.0'
 ```
 
-Crest is below `1.0`, so the pin stops short of `0.2.0` rather than admitting every `0.x`:
-`~> major.minor` only promises what it says once the major is real. From `1.0` on it will be
-`~> 1.0`, and `bundle update` will never cross a breaking change.
+`~> major.minor` is what makes that safe: `bundle update` takes every fix and every feature
+Crest ships, and never crosses a breaking change, because the major only moves when the API
+does — and from `1.0` on it moves only on purpose.
 
 ## Handing out a card
 
@@ -36,9 +36,9 @@ Crest.configure do |config|
   config.name  = 'HouseAccount'
   config.org   = 'HouseAccount'
   config.url   = 'https://houseaccount.com/'
-  config.email = 'hello@houseaccount.com'
+  config.email = 'support@houseaccount.com'
   config.photo = Rails.root.join 'public/cube.png'
-  config.phone = -> { Delivery::Twilio.sender }
+  config.phone = -> { Twilio.sender }
 end
 ```
 
@@ -52,21 +52,14 @@ saves under a blank name. Everything else is left out of the card when you do no
 That is what makes a number read out of the environment safe: production and staging differ, and
 a value read once at boot would be wrong in one of them until a restart.
 
-The picture is bytes, or a path the gem reads. It is read from disk once, and PNG and JPEG are
-told apart by the image's own first bytes rather than by anything you have to declare.
+The picture is bytes, or a path the gem reads, read afresh for each card, so replacing the file
+replaces the picture. PNG and JPEG are told apart by the image's own first bytes rather than by
+anything you have to declare, and anything else is warned about on stderr and left off the card
+— a public route is the wrong place to discover that somebody swapped a file.
 
-## Why a route and not an engine to mount
-
-You name the path, because the filename is your app's own name. And because it is a route rather
-than an engine, the line goes wherever you want it — inside a `scope`, behind a `constraints`,
-under a subdomain — which a mount point cannot do.
-
-## Why the controller is not your ApplicationController
-
-`Crest::CardsController` descends from `ActionController::Base`, not from your
-`ApplicationController`. That is deliberate and it is the surprising half: the card is public by
-definition — a phone fetches it with no session — so an inherited `before_action :authenticate`
-would refuse the one request the gem exists to answer.
+**The card is an organization's.** `N:` carries the one name a business has, which is why `name`
+is a single setting. A person's card wants a given name and a family name in their own fields,
+and Crest does not take them.
 
 ## Without Rails
 
@@ -75,7 +68,7 @@ The builder is plain Ruby and loads on its own, Rails or no Rails:
 ```ruby
 require 'crest/card'
 
-Crest::Card.new(name: 'HouseAccount', phone: '+18005550100',
+Crest::Card.new(name: 'HouseAccount', phone: '+17744687322',
                 url: 'https://houseaccount.com/', photo: 'cube.png').to_s
 ```
 

data/lib/crest/card.rb

@@ -1,12 +1,12 @@
 require 'crest/photo'
 
 module Crest
-  # A contact card a phone offers to save, written as the vCard 3.0 every phone reads.
+  # An organization's contact card, written as the vCard 3.0 a phone offers to save.
   class Card
     # What a line may hold before a vCard folds it, less the space that continues it.
     FOLD = 74
 
-    # @param name [String] name the card is saved under.
+    # @param name [String] organization the card is saved under.
     # @param phone [String] number in the form a phone should dial it.
     # @param url [String] address of the site behind the name.
     # @param email [String] address somebody may write back to.
@@ -34,7 +34,7 @@ module Crest
         "TEL;TYPE=CELL:#{@phone}",
         ("URL:#{@url}" if @url),
         ("EMAIL;TYPE=INTERNET:#{@email}" if @email),
-        (Photo.of(@photo).to_s if @photo),
+        (Photo.new(@photo).property if @photo),
         'END:VCARD',
       ].compact
     end

data/lib/crest/photo.rb

@@ -1,32 +1,22 @@
-require 'crest/error'
-
 module Crest
   # The picture a card carries: bytes as they were handed over, or the file a path names.
   class Photo
     # The first bytes of each image format a phone will read a saved card's picture from.
     SIGNATURES = { 'PNG' => "\x89PNG".b, 'JPEG' => "\xFF\xD8\xFF".b }
 
-    # The picture a path or a string of bytes stands for, read from disk only the first time,
-    # so a card handed out a thousand times costs one read and one encoding.
-    # @return [Crest::Photo] picture that file holds, or those bytes are.
-    def self.of(photo)
-      @read ||= {}
-      @read[photo] ||= new photo
-    end
+    # What a host hears about a picture no phone would draw.
+    UNREADABLE = 'crest: the photo is neither a PNG nor a JPEG, so the card goes out without it'
 
     # @param photo [String, Pathname] image bytes, or the file to read them from.
     def initialize(photo)
       @bytes = photo.respond_to?(:binread) ? photo.binread : photo
+      @type = SIGNATURES.find { |_, signature| @bytes.b.start_with? signature }&.first
+      warn UNREADABLE unless @type
     end
 
-    # @return [String] PHOTO property, base64-encoded and typed by the image's own first bytes.
-    def to_s = @property ||= "PHOTO;ENCODING=b;TYPE=#{type}:#{[@bytes].pack 'm0'}"
-
-  private
-
-    def type
-      SIGNATURES.find { |_, signature| @bytes.b.start_with? signature }&.first ||
-        raise(Error, 'a photo has to be a PNG or a JPEG')
+    # @return [String] PHOTO property, or nothing where the bytes are in no format a phone reads.
+    def property
+      @property ||= "PHOTO;ENCODING=b;TYPE=#{@type}:#{[@bytes].pack 'm0'}" if @type
     end
   end
 end

data/lib/crest/version.rb

@@ -1,4 +1,4 @@
 module Crest
   # The version of this gem, as RubyGems knows it.
-  VERSION = '0.1.1'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crest
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo