rename: web_push -> web_push_ex

Author: kenichi

README.md

@@ -1,22 +1,19 @@
-# WebPush
+# WebPushEx
 
-This library implements RFC 8291 Message Encryption for Web Push.
+This library implements
+[RFC 8291](https://datatracker.ietf.org/doc/html/rfc8291/) Message Encryption
+for Web Push in Elixir.
 
 It generates request details but does not make the HTTP POST request itself. The
 generated details should be enough to feed to your HTTP client of choice.
 
-## Installation
-
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `web_push` to your list of dependencies in `mix.exs`:
+#### Features
 
-```elixir
-def deps do
-  [
-    {:web_push, "~> 0.1.0"}
-  ]
-end
-```
+* `aes128gcm` content encoding method
+* uses `:json` (requires Erlang/OTP >=27)
+* uses JOSE for handling JWT
+* bring your own HTTP client
+* tested using RFC examples
 
 ## Configuration
 
@@ -27,18 +24,18 @@ generated config to your needs:
 $ mix web_push.vapid
 # in config/config.exs:
 
-    config :web_push, :vapid,
+    config :web_push_ex, :vapid,
       public_key: "<base64 encoded public key>"
       subject: "[email protected]"
 
 # in config/runtime.exs:
 
-    config :web_push, :vapid,
+    config :web_push_ex, :vapid,
       private_key: System.fetch_env!("WEB_PUSH_VAPID_PRIVATE_KEY")
 
 # in your environment:
 
-    export WEB_PUSH_VAPID_PRIVATE_KEY=<base64 encoded private key>
+    export WEB_PUSH_EX_VAPID_PRIVATE_KEY=<base64 encoded private key>
 ```
 
 ## Usage
@@ -54,21 +51,21 @@ pushManager.subscribe({
 }).then(...);
 ```
 
-Once you have your subscription data, you may construct a `WebPush.Request` and
+Once you have your subscription data, you may construct a `WebPushEx.Request` and
 use it to make the push notification via the HTTP client of your choice.
 
 ```elixir
 # create the struct from the subscription JSON data
 subscription =
-  WebPush.Subscription.from_json("""
+  WebPushEx.Subscription.from_json("""
   {"endpoint":"https://push.example.com/123","keys":{"p256dh":"user_agent_public_key","auth":"auth_secret"}}
   """)
 
 # structured message, see example serviceWorker.js linked below
 message = %{title: "Notification Title", body: "lorem ipsum etc"}
 
 # generate request details
-%WebPush.Request{} = request = WebPush.request(subscription, :json.encode(message))
+%WebPushEx.Request{} = request = WebPushEx.request(subscription, :json.encode(message))
 
 request.endpoint
 # => "https://push.example.com/123"
@@ -86,14 +83,29 @@ request.headers
 #   "Urgency" => "normal"
 # }
 
-# send web push notification via http client e.g. tesla
-Tesla.post(request.endpoint, request.body, headers: Map.to_list(request.headers))
+# send web push notification via http client e.g. req
+{:ok, resp} = Req.post(request.endpoint, body: request.body, headers: request.headers)
+```
+
+## Installation
+
+If [available in Hex](https://hex.pm/docs/publish), the package can be installed
+by adding `web_push` to your list of dependencies in `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:web_push_ex, "~> 0.1.0"}
+  ]
+end
 ```
 
 ## tl()
 
 #### Motivation && Inspiration
 
+Many thanks to maintainers and contributors to all these repos 🙇
+
 * [web-push-elixir](https://github.com/midarrlabs/web-push-elixir)
 * [web-push-encryption](https://github.com/tuvistavie/elixir-web-push-encryption)
 * [web-push](https://github.com/web-push-libs/web-push)

config/dev.exs

@@ -3,7 +3,7 @@ import Config
 # use OTP :json for development
 config :jose, :json_module, WebPush.JOSEjson
 
-config :web_push, :vapid,
+config :web_push_ex, :vapid,
   public_key: "",
   private_key: "",
   subject: "[email protected]"

config/test.exs

@@ -1,9 +1,9 @@
 import Config
 
 # use OTP :json for testing
-config :jose, :json_module, WebPush.JOSEjson
+config :jose, :json_module, WebPushEx.JOSEjson
 
-config :web_push, :vapid,
+config :web_push_ex, :vapid,
   public_key: "",
   private_key: "",
   subject: "[email protected]"

lib/mix/tasks/web_push/vapid.ex

@@ -1,4 +1,4 @@
-defmodule Mix.Tasks.WebPush.Vapid do
+defmodule Mix.Tasks.WebPushEx.Vapid do
   @moduledoc """
   Generate VAPID keys for config.
 
@@ -23,24 +23,24 @@ defmodule Mix.Tasks.WebPush.Vapid do
 
   defp encode({public_key, private_key}), do: {encode(public_key), encode(private_key)}
 
-  defp encode(key), do: Base.url_encode64(key, padding: false)
+  defp encode(key), do: WebPushEx.encode(key)
 
   defp build_config_message({public_key, private_key}) do
     """
     # in config/config.exs:
 
-        config :web_push, :vapid,
+        config :web_push_ex, :vapid,
           public_key: "#{public_key}",
           subject: "[email protected]"
 
     # in config/runtime.exs:
 
-        config :web_push, :vapid,
-          private_key: System.fetch_env!("WEB_PUSH_VAPID_PRIVATE_KEY")
+        config :web_push_ex, :vapid,
+          private_key: System.fetch_env!("WEB_PUSH_EX_VAPID_PRIVATE_KEY")
 
     # in your environment:
 
-        export WEB_PUSH_VAPID_PRIVATE_KEY=#{private_key}
+        export WEB_PUSH_EX_VAPID_PRIVATE_KEY=#{private_key}
     """
   end
 end

lib/web_push.ex

@@ -1,11 +1,11 @@
-defmodule WebPush do
+defmodule WebPushEx do
   @moduledoc """
   Web Push notifications via `aes128gcm`.
 
   Implementation of RFC 8291, 8188, & 5689.
   """
 
-  alias WebPush.{Request, Subscription}
+  alias WebPushEx.{Request, Subscription}
 
   @base64_options [padding: false]
   @default_exp 12 * 60 * 60
@@ -176,7 +176,7 @@ defmodule WebPush do
 
   @spec fetch_vapid!(vapid_key(), boolean()) :: String.t()
   defp fetch_vapid!(key, decode \\ true) do
-    :web_push
+    :web_push_ex
     |> Application.fetch_env!(:vapid)
     |> Keyword.fetch!(key)
     |> decode_if(key, decode)

lib/web_push/jose_json.ex

@@ -1,4 +1,4 @@
-defmodule WebPush.JOSEjson do
+defmodule WebPushEx.JOSEjson do
   @moduledoc """
   :json wrapper for JOSE.
   """

lib/web_push/request.ex

@@ -1,4 +1,4 @@
-defmodule WebPush.Request do
+defmodule WebPushEx.Request do
   @moduledoc """
   Request details ready for sending to the subscription endpoint.
   """

lib/web_push/subscription.ex

@@ -1,4 +1,4 @@
-defmodule WebPush.Subscription do
+defmodule WebPushEx.Subscription do
   @moduledoc """
   Subscription data structure.
   """

mix.exs

@@ -1,12 +1,12 @@
-defmodule WebPush.MixProject do
+defmodule WebPushEx.MixProject do
   use Mix.Project
 
-  @source_url "https://github.com/kenichi/web-push"
+  @source_url "https://github.com/kenichi/web-push-ex"
   @version "0.1.0"
 
   def project do
     [
-      app: :web_push,
+      app: :web_push_ex,
       version: @version,
       elixir: "~> 1.17",
       elixirc_paths: elixirc_paths(Mix.env()),

test/support/web_push_fixtures.ex renamed to test/support/web_push_ex_fixtures.ex

@@ -1,11 +1,11 @@
-defmodule WebPushFixtures do
+defmodule WebPushExFixtures do
   @moduledoc """
   Example data from RFC 8291, section 5.
 
   see: https://datatracker.ietf.org/doc/html/rfc8291/#section-5
   """
 
-  import WebPush, only: [decode: 1]
+  import WebPushEx, only: [decode: 1]
 
   @doc """
   WebPushSubscription fixture with default `p256dh` and `auth` values from the
@@ -21,7 +21,7 @@ defmodule WebPushFixtures do
         auth: "BTBZMqHH6r4Tts7J_aSIgg"
       }
     })
-    |> then(&struct!(WebPush.Subscription, &1))
+    |> then(&struct!(WebPushEx.Subscription, &1))
   end
 
   @doc """

test/web_push_test.exs renamed to test/web_push_ex_test.exs

@@ -1,14 +1,12 @@
-defmodule WebPushTest do
+defmodule WebPushExTest do
   use ExUnit.Case, async: true
 
-  import WebPushFixtures
-
-  alias WebPush
+  import WebPushExFixtures
 
   describe "request/3" do
     test "generates details according to example in section 5/appendix A" do
       wps = web_push_subscription_fixture()
-      request = WebPush.request(wps, plaintext(), as_key_pair: as_key_pair(), salt: salt())
+      request = WebPushEx.request(wps, plaintext(), as_key_pair: as_key_pair(), salt: salt())
 
       assert request.headers
              |> Map.get("Authorization")
@@ -18,7 +16,7 @@ defmodule WebPushTest do
       refute Map.has_key?(request.headers, "Crypto-Key")
       assert Map.get(request.headers, "Urgency") == "normal"
 
-      assert request.body == WebPush.decode(expected())
+      assert request.body == WebPushEx.decode(expected())
 
       <<salt::binary-size(16), rs::unsigned-big-integer-size(32), idlen::8,
         keyid::binary-size(idlen), _ciphertext::binary>> = request.body
@@ -33,7 +31,7 @@ defmodule WebPushTest do
   describe "from_json/1" do
     test "decodes to struct" do
       observed =
-        WebPush.Subscription.from_json("""
+        WebPushEx.Subscription.from_json("""
         {
           "endpoint": "https://push.example.com/123",
           "keys": {
@@ -48,5 +46,19 @@ defmodule WebPushTest do
       assert observed.endpoint == URI.parse(expected.endpoint)
       assert observed.keys == expected.keys
     end
+
+    test "raises with invalid keys" do
+      assert_raise ArgumentError, fn ->
+        WebPushEx.Subscription.from_json("""
+        {
+          "end": "https://push.example.com/123",
+          "key": {
+            "p256": "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4",
+            "au": "BTBZMqHH6r4Tts7J_aSIgg"
+          }
+        }
+        """)
+      end
+    end
   end
 end