create an API endpoint for querying the doc build status of a package

tayloraswift · tayloraswift · commit 7ff3273ebcba · 2023-09-23T22:42:55.000Z
diff --git a/Sources/HTTP/ServerResponseFactory.swift b/Sources/HTTP/ServerResponseFactory.swift
@@ -1,7 +1,7 @@
+import Media
+
 public
-protocol ServerResponseFactory<Request>
+protocol ServerResponseFactory
 {
-    associatedtype Request
-
-    func response(for requested:Request) throws -> ServerResponse
+    func response(as type:AcceptType?) throws -> ServerResponse
 }
diff --git a/Sources/Media/AcceptType.swift b/Sources/Media/AcceptType.swift
@@ -0,0 +1,11 @@
+@frozen public
+enum AcceptType:Equatable, Hashable, Sendable
+{
+    case application(MediaSubtype?)
+    case audio      (MediaSubtype?)
+    case font       (MediaSubtype?)
+    case image      (MediaSubtype?)
+    case model      (MediaSubtype?)
+    case text       (MediaSubtype?)
+    case video      (MediaSubtype?)
+}
diff --git a/Sources/UnidocPages/API/Site.API.Get.swift b/Sources/UnidocPages/API/Site.API.Get.swift
@@ -3,6 +3,7 @@ extension Site.API
     @frozen public
     enum Get:String
     {
+        case build
         case github
         case register
     }
diff --git a/Sources/UnidocPages/Responses/PackageEditionsQuery.Output (ext).swift b/Sources/UnidocPages/Responses/PackageEditionsQuery.Output (ext).swift
@@ -1,13 +1,58 @@
 import HTTP
+import JSON
+import Media
+import UnidocDB
 import UnidocQueries
 import URI
 
 extension PackageEditionsQuery.Output:ServerResponseFactory
 {
     public
-    func response(for _:URI) throws -> ServerResponse
+    func response(as type:AcceptType?) throws -> ServerResponse
     {
-        let list:Site.Tags.List = .init(from: self)
-        return .ok(list.resource())
+        switch type
+        {
+        case .application(.json):
+            let json:JSON = .object
+            {
+                guard
+                let repo:PackageRepo = self.record.repo,
+                let release:PackageEditionsQuery.Facet = self.releases.first
+                else
+                {
+                    return
+                }
+
+                $0["repo"] = "https://\(repo.origin)"
+
+                $0["release"]
+                {
+                    $0["graphs"] = release.graphs?.count ?? 0
+                    $0["tag"] = release.edition.name
+                }
+
+                guard
+                let prerelease:PackageEditionsQuery.Facet = self.prereleases.first,
+                    prerelease.edition.patch > release.edition.patch
+                else
+                {
+                    return
+                }
+
+                $0["prerelease"]
+                {
+                    $0["graphs"] = prerelease.graphs?.count ?? 0
+                    $0["tag"] = prerelease.edition.name
+                }
+            }
+
+            return .ok(.init(
+                content: .binary(json.utf8),
+                type: .application(.json, charset: .utf8)))
+
+        case _:
+            let list:Site.Tags.List = .init(from: self)
+            return .ok(list.resource())
+        }
     }
 }
diff --git a/Sources/UnidocPages/Responses/SearchIndexQuery.Output (ext).swift b/Sources/UnidocPages/Responses/SearchIndexQuery.Output (ext).swift
@@ -1,11 +1,12 @@
 import HTTP
+import Media
 import UnidocQueries
 import URI
 
 extension SearchIndexQuery.Output:ServerResponseFactory
 {
     public
-    func response(for _:URI) throws -> ServerResponse
+    func response(as _:AcceptType?) throws -> ServerResponse
     {
         let content:ServerResource.Content
         switch self.json
diff --git a/Sources/UnidocPages/Responses/ThinQuery.Output (ext).swift b/Sources/UnidocPages/Responses/ThinQuery.Output (ext).swift
@@ -1,12 +1,13 @@
 import HTTP
+import Media
 import UnidocQueries
 import UnidocRecords
 import URI
 
 extension ThinQuery.Output:ServerResponseFactory
 {
     public
-    func response(for _:URI) throws -> ServerResponse
+    func response(as _:AcceptType?) throws -> ServerResponse
     {
         if  LookupPredicate.self is Volume.Range.Type
         {
diff --git a/Sources/UnidocPages/Responses/WideQuery.Output (ext).swift b/Sources/UnidocPages/Responses/WideQuery.Output (ext).swift
@@ -1,12 +1,13 @@
 import HTTP
+import Media
 import UnidocQueries
 import UnidocRecords
 import URI
 
 extension WideQuery.Output:ServerResponseFactory
 {
     public
-    func response(for _:URI) throws -> ServerResponse
+    func response(as _:AcceptType?) throws -> ServerResponse
     {
         guard let principal:WideQuery.Output.Principal = self.principal
         else
diff --git a/Sources/UnidocServer/Operations/Server.Endpoint.swift b/Sources/UnidocServer/Operations/Server.Endpoint.swift
@@ -73,27 +73,6 @@ extension Server.Endpoint
                 return nil
             }
 
-        case Site.API.root:
-            switch Site.API.Get.init(trunk)
-            {
-            case nil:
-                return nil
-
-            case .github?:
-                if  let parameters:[(String, String)] = uri.query?.parameters,
-                    let operation:Server.Operation.Login = .init(parameters: parameters)
-                {
-                    return .interactive(operation)
-                }
-
-            case .register?:
-                if  let parameters:[(String, String)] = uri.query?.parameters,
-                    let operation:Server.Operation.Register = .init(parameters: parameters)
-                {
-                    return .interactive(operation)
-                }
-            }
-
         case Site.Asset.root:
             let asset:Site.Asset.Get? = .init(trunk)
             return asset.map { .static(.init($0, tag: tag)) }
@@ -130,16 +109,47 @@ extension Server.Endpoint
 
         switch root
         {
+        case Site.API.root:
+            switch Site.API.Get.init(trunk)
+            {
+            case nil:
+                return nil
+
+            case .build?:
+                if  let package:String = stem.first
+                {
+                    return .interactive(Server.Operation.Pipeline<PackageEditionsQuery>.init(
+                        output: explain ? nil : .application(.json),
+                        query: .init(package: .init(package), limit: 1),
+                        uri: uri,
+                        tag: tag))
+                }
+
+            case .github?:
+                if  let parameters:[(String, String)] = uri.query?.parameters,
+                    let operation:Server.Operation.Login = .init(parameters: parameters)
+                {
+                    return .interactive(operation)
+                }
+
+            case .register?:
+                if  let parameters:[(String, String)] = uri.query?.parameters,
+                    let operation:Server.Operation.Register = .init(parameters: parameters)
+                {
+                    return .interactive(operation)
+                }
+            }
+
         case Site.Tags.root:
             return .interactive(Server.Operation.Pipeline<PackageEditionsQuery>.init(
-                explain: explain,
+                output: explain ? nil : .text(.html),
                 query: .init(package: .init(trunk)),
                 uri: uri,
                 tag: tag))
 
         case Site.Docs.root:
             return .interactive(Server.Operation.Pipeline<WideQuery>.init(
-                explain: explain,
+                output: explain ? nil : .text(.html),
                 query: .init(
                     volume: .init(trunk),
                     lookup: .init(stem: stem, hash: hash)),
@@ -148,7 +158,7 @@ extension Server.Endpoint
 
         case Site.Guides.root:
             return .interactive(Server.Operation.Pipeline<ThinQuery<Volume.Range>>.init(
-                explain: explain,
+                output: explain ? nil : .text(.html),
                 query: .init(
                     volume: .init(trunk),
                     lookup: .articles),
@@ -157,7 +167,7 @@ extension Server.Endpoint
 
         case "articles":
             return .interactive(Server.Operation.Pipeline<WideQuery>.init(
-                explain: explain,
+                output: explain ? nil : .text(.html),
                 query: .init(
                     volume: .init(package: "__swiftinit", version: "0.0.0"),
                     lookup: .init(stem: ["Articles", trunk], hash: nil)),
@@ -169,7 +179,7 @@ extension Server.Endpoint
             {
                 return .interactive(
                     Server.Operation.Pipeline<SearchIndexQuery<VolumeIdentifier>>.init(
-                    explain: explain,
+                    output: explain ? nil : .application(.json),
                     query: .init(
                         from: UnidocDatabase.Search.name,
                         tag: tag,
@@ -181,22 +191,20 @@ extension Server.Endpoint
             {
                 return .interactive(
                     Server.Operation.Pipeline<SearchIndexQuery<Int32>>.init(
-                    explain: explain,
+                    output: explain ? nil : .application(.json),
                     query: .init(
                         from: UnidocDatabase.Meta.name,
                         tag: tag,
                         id: 0),
                     uri: uri,
                     tag: tag))
             }
-            else
-            {
-                return nil
-            }
 
         case _:
-            return nil
+            break
         }
+
+        return nil
     }
 
     private static
@@ -223,14 +231,14 @@ extension Server.Endpoint
         if  let overload:Symbol.Decl
         {
             return .interactive(Server.Operation.Pipeline<ThinQuery<Symbol.Decl>>.init(
-                explain: false,
+                output: .text(.html),
                 query: .init(volume: query.volume, lookup: overload),
                 uri: uri))
         }
         else
         {
             return .interactive(Server.Operation.Pipeline<ThinQuery<Volume.Shoot>>.init(
-                explain: false,
+                output: .text(.html),
                 query: query,
                 uri: uri))
         }
diff --git a/Sources/UnidocServer/Operations/Server.Operation.Pipeline.swift b/Sources/UnidocServer/Operations/Server.Operation.Pipeline.swift
@@ -1,4 +1,5 @@
 import HTTP
+import Media
 import MD5
 import MongoDB
 import UnidocDB
@@ -8,21 +9,22 @@ import URI
 extension Server.Operation
 {
     struct Pipeline<Query>:Sendable
-        where   Query:DatabaseQuery,
-                Query.Output:ServerResponseFactory<URI>
+        where Query:DatabaseQuery, Query.Output:ServerResponseFactory
     {
-        let explain:Bool
+        /// If nil, the query will be explained instead of executed. If non-nil, this field
+        /// will be passed to the query’s output type, which may influence the response it
+        /// produces.
+        let output:AcceptType?
         let query:Query
         let uri:URI
         let tag:MD5?
 
-        init(
-            explain:Bool,
+        init(output:AcceptType?,
             query:Query,
             uri:URI,
             tag:MD5? = nil)
         {
-            self.explain = explain
+            self.output = output
             self.query = query
             self.uri = uri
             self.tag = tag
@@ -49,7 +51,9 @@ extension Server.Operation.Pipeline:UnrestrictedOperation
     func load(from db:UnidocDatabase,
         with session:Mongo.Session) async throws -> ServerResponse?
     {
-        if  self.explain
+        guard
+        let accept:AcceptType = self.output
+        else
         {
             let explanation:String = try await db.explain(
                 query: self.query,
@@ -67,7 +71,7 @@ extension Server.Operation.Pipeline:UnrestrictedOperation
             return nil
         }
 
-        switch try output.response(for: self.uri)
+        switch try output.response(as: accept)
         {
         case .redirect(let redirect, cookies: let cookies):
             return .redirect(redirect, cookies: cookies)
diff --git a/Sources/UnidocServer/Operations/Server.Operation.swift b/Sources/UnidocServer/Operations/Server.Operation.swift
@@ -54,7 +54,7 @@ extension Server.Operation:HTTPServerOperation
             //  Hilariously, we don’t have a home page yet. So we just redirect to the docs
             //  for the standard library.
             let get:Server.Endpoint = .interactive(Server.Operation.Pipeline<WideQuery>.init(
-                explain: false,
+                output: .text(.html),
                 query: .init(
                     volume: .init(package: .swift, version: nil),
                     lookup: .init(stem: [])),

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
	`1`	`+import Media`
	`2`	`+`
`1`	`3`	`public`
`2`		`-protocol ServerResponseFactory<Request>`
	`4`	`+protocol ServerResponseFactory`
`3`	`5`	`{`
`4`		`- associatedtype Request`
`5`		`-`
`6`		`- func response(for requested:Request) throws -> ServerResponse`
	`6`	`+ func response(as type:AcceptType?) throws -> ServerResponse`
`7`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@ extension Site.API`
`3`	`3`	`@frozen public`
`4`	`4`	`enum Get:String`
`5`	`5`	`{`
	`6`	`+ case build`
`6`	`7`	`case github`
`7`	`8`	`case register`
`8`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,12 @@`
`1`	`1`	`import HTTP`
	`2`	`+import Media`
`2`	`3`	`import UnidocQueries`
`3`	`4`	`import URI`
`4`	`5`
`5`	`6`	`extension SearchIndexQuery.Output:ServerResponseFactory`
`6`	`7`	`{`
`7`	`8`	`public`
`8`		`- func response(for _:URI) throws -> ServerResponse`
	`9`	`+ func response(as _:AcceptType?) throws -> ServerResponse`
`9`	`10`	`{`
`10`	`11`	`let content:ServerResource.Content`
`11`	`12`	`switch self.json`
Original file line number	Diff line number	Diff line change
`@@ -1,12 +1,13 @@`
`1`	`1`	`import HTTP`
	`2`	`+import Media`
`2`	`3`	`import UnidocQueries`
`3`	`4`	`import UnidocRecords`
`4`	`5`	`import URI`
`5`	`6`
`6`	`7`	`extension ThinQuery.Output:ServerResponseFactory`
`7`	`8`	`{`
`8`	`9`	`public`
`9`		`- func response(for _:URI) throws -> ServerResponse`
	`10`	`+ func response(as _:AcceptType?) throws -> ServerResponse`
`10`	`11`	`{`
`11`	`12`	`if LookupPredicate.self is Volume.Range.Type`
`12`	`13`	`{`