improve error responses

Author: tayloraswift

Sources/UnidocAssets/Unidoc.Asset.swift

@@ -10,6 +10,8 @@ extension Unidoc
         case favicon_ico        = "favicon.ico"
         case favicon_png        = "favicon.png"
 
+        case github_jpg         = "github.jpg"
+
         //  We let Google Fonts serve most of the fonts, but we host Literata ourselves
         //  because the front-end CSS uses opentype features such as old-style numerals,
         //  and Google Fonts strips those out.
@@ -62,6 +64,7 @@ extension Unidoc.Asset
         case .error500_jpg:     false
         case .favicon_ico:      false
         case .favicon_png:      false
+        case .github_jpg:       false
         case .literata45_woff2: false
         case .literata47_woff2: false
         case .literata75_woff2: false

Sources/UnidocAssets_System/Unidoc.Asset (ext).swift

@@ -14,6 +14,7 @@ extension Unidoc.Asset
         case .error500_jpg:     ["icons", "error500.jpg"]
         case .favicon_ico:      ["icons", "favicon.ico"]
         case .favicon_png:      ["icons", "favicon.png"]
+        case .github_jpg:       ["icons", "github.jpg"]
         case .literata45_woff2: ["woff2", "Literata_24pt-Regular.woff2"]
         case .literata47_woff2: ["woff2", "Literata_24pt-Italic.woff2"]
         case .literata75_woff2: ["woff2", "Literata_24pt-Bold.woff2"]
@@ -37,6 +38,7 @@ extension Unidoc.Asset
         case .error500_jpg:     .image(.jpeg)
         case .favicon_ico:      .image(.x_icon)
         case .favicon_png:      .image(.png)
+        case .github_jpg:       .image(.jpeg)
         case .literata45_woff2: .font(.woff2)
         case .literata47_woff2: .font(.woff2)
         case .literata75_woff2: .font(.woff2)

Sources/UnidocServer/Operations/Interactions/Unidoc.PackageIndexOperation.swift

@@ -45,7 +45,7 @@ extension Unidoc.PackageIndexOperation:Unidoc.MeteredOperation
 
         switch self.subject
         {
-        case .repo(owner: let owner, name: let repo, githubInstallation: let appInstallation):
+        case .repo(owner: let owner, name: let name, githubInstallation: let appInstallation):
             if  let error:Unidoc.PolicyErrorPage = try await self.charge(cost: 8,
                     from: server,
                     with: session)
@@ -56,15 +56,19 @@ extension Unidoc.PackageIndexOperation:Unidoc.MeteredOperation
             let repo:GitHub.Repo? = try await github.connect(
                 with: .init(githubInstallation: appInstallation))
             {
-                try await $0.lookup(owner: owner, repo: repo)
+                try await $0.lookup(owner: owner, repo: name)
             }
 
             guard
             let repo:GitHub.Repo
             else
             {
-                let display:Unidoc.PolicyErrorPage = .init(illustration: .error404_jpg,
-                    message: "No such GitHub repository!",
+                let display:Unidoc.PolicyErrorPage = .init(illustration: .github_jpg,
+                    heading: "No such GitHub repository!",
+                    message: """
+                    The role you selected does not have access to a GitHub repository with the \
+                    name '\(owner)/\(name)'.
+                    """,
                     status: 404)
                 return display.response(format: format)
             }
@@ -89,7 +93,7 @@ extension Unidoc.PackageIndexOperation:Unidoc.MeteredOperation
                     with: session)
             }
 
-        case .ref(let id, ref: let ref):
+        case .ref(let id, ref: let name):
             if  let metadata:Unidoc.PackageMetadata = try await server.db.packages.find(id: id,
                     with: session)
             {
@@ -116,14 +120,21 @@ extension Unidoc.PackageIndexOperation:Unidoc.MeteredOperation
 
             let ref:GitHub.Ref? = try await github.connect(with: .init())
             {
-                try await $0.lookup(owner: origin.owner, repo: origin.name, ref: ref)
+                try await $0.lookup(owner: origin.owner, repo: origin.name, ref: name)
             }
 
             guard
             let ref:GitHub.Ref
             else
             {
-                return .notFound("No such ref")
+                let display:Unidoc.PolicyErrorPage = .init(illustration: .github_jpg,
+                    heading: "No such ref!",
+                    message: """
+                    Could not find the ref '\(name)' in the GitHub repository \
+                    '\(origin.owner)/\(origin.name)'.
+                    """,
+                    status: 404)
+                return display.response(format: format)
             }
 
             let version:SemanticVersion? = package.symbol.version(tag: ref.name)
@@ -174,6 +185,7 @@ extension Unidoc.PackageIndexOperation
             if  rights < .editor
             {
                 return .init(illustration: .error4xx_jpg,
+                    heading: "Insufficient permissions",
                     message: "You are not authorized to index this repository!",
                     status: 403)
             }
@@ -186,6 +198,7 @@ extension Unidoc.PackageIndexOperation
         else
         {
             return .init(illustration: .error4xx_jpg,
+                heading: "Server policy error",
                 message: "Cannot index a repository with a dot in the owner’s name!",
                 status: 400)
         }

Sources/UnidocServer/Operations/Interactive/Unidoc.MeteredOperation.swift

@@ -48,7 +48,10 @@ extension Unidoc.MeteredOperation
         else
         {
             return .init(illustration: .error4xx_jpg,
-                message: "Inactive or nonexistent API key",
+                heading: "Inactive or nonexistent API key",
+                message: """
+                The key may have been changed, or it may have exceeded its hourly rate limit.
+                """,
                 status: 429)
         }
     }

Sources/UnidocServer/Server/Unidoc.PolicyErrorPage.swift

@@ -6,12 +6,14 @@ extension Unidoc
     struct PolicyErrorPage
     {
         let illustration:Unidoc.Asset
+        let heading:String
         let message:String
         let status:UInt
 
-        init(illustration:Unidoc.Asset, message:String, status:UInt)
+        init(illustration:Unidoc.Asset, heading:String, message:String, status:UInt)
         {
             self.illustration = illustration
+            self.heading = heading
             self.message = message
             self.status = status
         }
@@ -22,14 +24,15 @@ extension Unidoc.PolicyErrorPage:Unidoc.StatusBearingPage
 }
 extension Unidoc.PolicyErrorPage:Unidoc.RenderablePage, Unidoc.DynamicPage
 {
-    var title:String { "Policy error" }
+    var title:String { self.heading }
 }
 extension Unidoc.PolicyErrorPage:Unidoc.ApplicationPage
 {
     func main(_ main:inout HTML.ContentEncoder, format:Unidoc.RenderFormat)
     {
         main[.section]
         {
+            $0[.h1] = self.heading
             $0[.p] = self.message
             $0[.img]
             {