Standardize error handling to three-tuple map details

User prompts:
- "Expand registry error results to include details from storage adapters"
- "make the registry do most of the error handling, check for repo/upload existence early"
- "come up with a good error struct standard"
- "bump the minor level and open a PR"

Changes:
- Standardize all errors to {:error, atom_code, map()} three-tuple
- Add ensure_repo_exists/3 and ensure_upload_exists/4 precondition helpers to Registry
- Registry now checks repo/upload existence before delegating to storage
- Fix unhandled `false` fall-through in upload_blob_chunk and complete_blob_upload
- Convert all string error details to structured maps across auth, storage, handler
- Remove two-tuple error match from Handler (and the placeholder message)
- Update Storage.Adapter and Auth.Adapter callback specs to enforce map details
- Bump version to 0.2.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: coryodaniel

lib/oci/auth/adapter.ex

@@ -38,7 +38,7 @@ defmodule OCI.Auth.Adapter do
   """
   @type subject_t :: any()
 
-  @type error_details_t :: any()
+  @type error_details_t :: map()
 
   @callback init(config :: map()) :: {:ok, t()} | {:error, term()}
 

lib/oci/auth/static.ex

@@ -45,21 +45,24 @@ defmodule OCI.Auth.Static do
                   subject = username
                   {:ok, subject}
                 else
-                  {:error, :UNAUTHORIZED, "Invalid username or password"}
+                  {:error, :UNAUTHORIZED, %{reason: "Invalid username or password"}}
                 end
 
               _ ->
                 {:error, :UNAUTHORIZED,
-                 "Invalid authorization format, should be username:password"}
+                 %{reason: "Invalid authorization format, should be username:password"}}
             end
 
           :error ->
             {:error, :UNAUTHORIZED,
-             "Failed to decode authorization, should be base64 encoded username:password"}
+             %{
+               reason:
+                 "Failed to decode authorization, should be base64 encoded username:password"
+             }}
         end
 
       _other ->
-        {:error, :UNSUPPORTED, "Unsupported authentication scheme: #{scheme}"}
+        {:error, :UNSUPPORTED, %{reason: "Unsupported authentication scheme: #{scheme}"}}
     end
   end
 
@@ -73,18 +76,18 @@ defmodule OCI.Auth.Static do
 
         case required_action(ctx.method, ctx.endpoint) do
           nil ->
-            {:error, :DENIED}
+            {:error, :DENIED, %{repo: ctx.repo, method: ctx.method}}
 
           action ->
             if action in repo_perms do
               :ok
             else
-              {:error, :DENIED}
+              {:error, :DENIED, %{repo: ctx.repo, action: action}}
             end
         end
 
       _ ->
-        {:error, :DENIED}
+        {:error, :DENIED, %{subject: ctx.subject}}
     end
   end
 

lib/oci/plug.ex

@@ -34,7 +34,9 @@ defmodule OCI.Plug do
   end
 
   def call(conn, _opts) do
-    error_resp(conn, :UNSUPPORTED, "OCI Registry must be mounted at /#{Registry.api_version()}")
+    error_resp(conn, :UNSUPPORTED, %{
+      reason: "OCI Registry must be mounted at /#{Registry.api_version()}"
+    })
   end
 
   def authenticate(%{private: %{oci_registry: registry}} = conn) do
@@ -64,16 +66,13 @@ defmodule OCI.Plug do
       :ok ->
         conn
 
-      {:error, reason} ->
-        error_resp(conn, reason, nil)
-
       {:error, reason, details} ->
         error_resp(conn, reason, details)
     end
   end
 
   defp authorize(_) do
-    {:error, :UNAUTHORIZED}
+    {:error, :UNAUTHORIZED, %{}}
   end
 
   defp challenge_resp(conn) do

lib/oci/plug/handler.ex

@@ -30,15 +30,6 @@ defmodule OCI.Plug.Handler do
           %Plug.Conn{} = conn ->
             conn
 
-          {:error, oci_error_status} ->
-            you_suck_and_are_a_bad_person_messsage = """
-            You suck and are a bad person.
-
-            Please return error details for #{oci_error_status} in #{inspect(ctx)}
-            """
-
-            error_resp(conn, oci_error_status, you_suck_and_are_a_bad_person_messsage)
-
           {:error, oci_error_status, details} ->
             error_resp(conn, oci_error_status, details)
         end
@@ -55,7 +46,7 @@ defmodule OCI.Plug.Handler do
           repo :: String.t(),
           id :: String.t(),
           ctx :: OCI.Context.t()
-        ) :: Plug.Conn.t() | {:error, atom()} | {:error, atom(), String.t()}
+        ) :: Plug.Conn.t() | {:error, atom(), map() | String.t()}
   defp dispatch(%{method: "GET"} = conn, :tags_list, registry, repo, _id, ctx) do
     pag = pagination(conn.query_params)
 
@@ -179,7 +170,7 @@ defmodule OCI.Plug.Handler do
         error_resp(
           conn,
           :BLOB_UPLOAD_INVALID,
-          "Content-Range header is required for PATCH requests"
+          %{reason: "Content-Range header is required for PATCH requests"}
         )
 
       _ ->
@@ -325,7 +316,7 @@ defmodule OCI.Plug.Handler do
     method = conn.method
     path = conn.request_path
 
-    {:error, :UNSUPPORTED, "Unsupported [#{method}] #{path}"}
+    {:error, :UNSUPPORTED, %{method: method, path: path}}
   end
 
   defp pagination(params) do
@@ -366,7 +357,6 @@ defmodule OCI.Plug.Handler do
                ctx
              ) do
           {:ok, _, _} -> :ok
-          {:error, reason} -> {:error, reason}
           {:error, reason, details} -> {:error, reason, details}
         end
     end

lib/oci/registry.ex

@@ -80,14 +80,13 @@ defmodule OCI.Registry do
   end
 
   @spec validate_repository_name(registry :: t(), repo :: repo_t()) ::
-          {:ok, repo :: repo_t()} | {:error, :NAME_INVALID, String.t()}
+          {:ok, repo :: repo_t()} | {:error, :NAME_INVALID, map()}
 
   def validate_repository_name(registry, repo) do
     if Regex.match?(registry.repo_name_pattern, repo) do
       {:ok, repo}
     else
-      {:error, :NAME_INVALID,
-       "Invalid repo name: #{repo}, must match pattern: #{inspect(registry.repo_name_pattern)}."}
+      {:error, :NAME_INVALID, %{repo: repo, pattern: inspect(registry.repo_name_pattern)}}
     end
   end
 
@@ -149,12 +148,11 @@ defmodule OCI.Registry do
     - `{:error, reason}` if the upload fails
   """
   def upload_blob_chunk(%{storage: storage}, repo, uuid, chunk, maybe_chunk_range, ctx) do
-    reg = adapter(storage)
-
-    with true <- reg.upload_exists?(storage, repo, uuid, ctx),
-         {:ok, size} <- reg.get_blob_upload_offset(storage, repo, uuid, ctx),
+    with :ok <- ensure_upload_exists(storage, repo, uuid, ctx),
+         {:ok, size} <- adapter(storage).get_blob_upload_offset(storage, repo, uuid, ctx),
          :ok <- verify_upload_order(size, maybe_chunk_range),
-         {:ok, range} <- reg.upload_blob_chunk(storage, repo, uuid, chunk, maybe_chunk_range, ctx) do
+         {:ok, range} <-
+           adapter(storage).upload_blob_chunk(storage, repo, uuid, chunk, maybe_chunk_range, ctx) do
       {:ok, blobs_uploads_path(repo, uuid), range}
     end
   end
@@ -185,22 +183,26 @@ defmodule OCI.Registry do
     do: {:error, :DIGEST_INVALID, %{repo: repo, uuid: uuid}}
 
   def complete_blob_upload(%{storage: storage}, repo, uuid, digest, ctx) do
-    with true <- adapter(storage).upload_exists?(storage, repo, uuid, ctx),
+    with :ok <- ensure_upload_exists(storage, repo, uuid, ctx),
          :ok <- adapter(storage).complete_blob_upload(storage, repo, uuid, digest, ctx) do
       {:ok, blobs_digest_path(repo, digest)}
     end
   end
 
   def cancel_blob_upload(%{storage: storage}, repo, uuid, ctx) do
-    adapter(storage).cancel_blob_upload(storage, repo, uuid, ctx)
+    with :ok <- ensure_upload_exists(storage, repo, uuid, ctx) do
+      adapter(storage).cancel_blob_upload(storage, repo, uuid, ctx)
+    end
   end
 
   def blob_exists?(%{storage: storage}, repo, digest, ctx) do
     adapter(storage).blob_exists?(storage, repo, digest, ctx)
   end
 
   def get_blob(%{storage: storage}, repo, digest, ctx) do
-    adapter(storage).get_blob(storage, repo, digest, ctx)
+    with :ok <- ensure_repo_exists(storage, repo, ctx) do
+      adapter(storage).get_blob(storage, repo, digest, ctx)
+    end
   end
 
   def delete_blob(%{enable_blob_deletion: false}, repo, digest, _ctx),
@@ -298,18 +300,18 @@ defmodule OCI.Registry do
   def referenced_blobs(_manifest), do: []
 
   def get_manifest(%{storage: storage}, repo, reference, ctx) do
-    adapter(storage).get_manifest(storage, repo, reference, ctx)
+    with :ok <- ensure_repo_exists(storage, repo, ctx) do
+      adapter(storage).get_manifest(storage, repo, reference, ctx)
+    end
   end
 
   def manifest_exists?(%{storage: storage}, repo, reference, ctx) do
     adapter(storage).manifest_exists?(storage, repo, reference, ctx)
   end
 
   def list_tags(%{storage: storage}, repo, pagination, ctx) do
-    if repo_exists?(storage, repo, ctx) do
+    with :ok <- ensure_repo_exists(storage, repo, ctx) do
       adapter(storage).list_tags(storage, repo, pagination, ctx)
-    else
-      {:error, :NAME_UNKNOWN, %{repo: repo}}
     end
   end
 
@@ -366,17 +368,14 @@ defmodule OCI.Registry do
   Returns {:ok, location} on success, {:error, :BLOB_UNKNOWN} if the source blob doesn't exist.
   """
   def mount_blob(%__MODULE__{storage: storage} = registry, repo, digest, from_repo, ctx) do
-    if repo_exists?(storage, from_repo, ctx) do
+    with :ok <- ensure_repo_exists(storage, from_repo, ctx) do
       if blob_exists?(registry, from_repo, digest, ctx) do
-        # credo:disable-for-next-line
         with :ok <- adapter(storage).mount_blob(storage, repo, digest, from_repo, ctx) do
           {:ok, blobs_digest_path(repo, digest)}
         end
       else
         initiate_blob_upload(registry, repo, ctx)
       end
-    else
-      {:error, :NAME_UNKNOWN, %{repo: repo}}
     end
   end
 
@@ -431,6 +430,25 @@ defmodule OCI.Registry do
     "/#{api_version()}/#{repo}/blobs/uploads/#{uuid}"
   end
 
+  # Precondition checks — used by registry functions to validate state before
+  # delegating to storage adapters.
+
+  defp ensure_repo_exists(storage, repo, ctx) do
+    if adapter(storage).repo_exists?(storage, repo, ctx) do
+      :ok
+    else
+      {:error, :NAME_UNKNOWN, %{repo: repo}}
+    end
+  end
+
+  defp ensure_upload_exists(storage, repo, uuid, ctx) do
+    if adapter(storage).upload_exists?(storage, repo, uuid, ctx) do
+      :ok
+    else
+      {:error, :BLOB_UPLOAD_UNKNOWN, %{repo: repo, uuid: uuid}}
+    end
+  end
+
   @doc """
   Calculates the range of a chunk of data.
   ## Examples