Merge pull request #18 from tayloraswift/https-everywhere

HTTPS everywhere

Author: tayloraswift

.gitignore

@@ -5,6 +5,7 @@
 .vscode
 
 Assets/secrets/
+TestCertificates/*.pem
 TestDeployment/data/
 
 node_modules/

Assets/css/Main.css

@@ -0,0 +1,41 @@
+# Generating TLS certificates
+
+To simplify the implementation and facilitate testing, Unidoc uses TLS (HTTPS) everywhere, even when running locally.
+
+For a seamless development experience, we recommend using [mkcert](https://github.com/FiloSottile/mkcert) to generate a local certificate authority (CA) for your development environment.
+
+## Installing mkcert
+
+The easiest way to install `mkcert` is to download one of its prebuilt binaries.
+
+```bash
+$ curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
+chmod +x mkcert-v*-linux-amd64
+```
+
+## Generating a local certificate authority
+
+```bash
+$ ./mkcert-v1.4.4-linux-amd64 -install
+``````
+
+## Generating a local certificate
+
+If the `mkcert-v1.4.4-linux-amd64` binary is located in your home directory, you can generate a certificate for `localhost` by running the following from the repository root:
+
+```bash
+$ cd TestCertificates
+$ ~/mkcert-v1.4.4-linux-amd64 localhost
+
+```
+
+Then, rename the generated files to `fullchain.pem` and `privkey.pem`.
+
+```bash
+$ mv localhost.pem fullchain.pem
+$ mv localhost-key.pem privkey.pem
+```
+
+You should now be able to run the Unidoc server locally and access it without browser warnings.
+
+Keep in mind that the certificate is only valid for `localhost`; hostnames like `0.0.0.0` will still raise browser warnings.

Guides/GeneratingCertificates.md

@@ -59,17 +59,17 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/tayloraswift/swift-mongodb",
       "state" : {
-        "revision" : "b2086401145ed500924ea1c6217fec06c0b0a212",
-        "version" : "0.8.2"
+        "revision" : "49a0dc9c7130810714ce062165323b4e499326f4",
+        "version" : "0.8.3"
       }
     },
     {
       "identity" : "swift-nio",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-nio.git",
       "state" : {
-        "revision" : "a2e487b77f17edbce9a65f2b7415f2f479dc8e48",
-        "version" : "2.57.0"
+        "revision" : "cf281631ff10ec6111f2761052aa81896a83a007",
+        "version" : "2.58.0"
       }
     },
     {

Package.resolved

@@ -74,12 +74,12 @@ let package:Package = .init(
         .package(url: "https://github.com/tayloraswift/swift-hash", .upToNextMinor(
             from: "0.5.0")),
         .package(url: "https://github.com/tayloraswift/swift-mongodb", .upToNextMinor(
-            from: "0.8.2")),
+            from: "0.8.3")),
 
         .package(url: "https://github.com/apple/swift-atomics", .upToNextMinor(
             from: "1.1.0")),
         .package(url: "https://github.com/apple/swift-nio", .upToNextMinor(
-            from: "2.57.0")),
+            from: "2.58.0")),
         .package(url: "https://github.com/apple/swift-nio-http2", .upToNextMinor(
             from: "1.27.0")),
         .package(url: "https://github.com/apple/swift-nio-ssl", .upToNextMinor(
@@ -177,6 +177,7 @@ let package:Package = .init(
                 .target(name: "HTML"),
                 .target(name: "HTTP"),
                 .product(name: "NIOHTTP1", package: "swift-nio"),
+                .product(name: "NIOHTTP2", package: "swift-nio-http2"),
                 .product(name: "NIOSSL", package: "swift-nio-ssl"),
                 .product(name: "TraceableErrors", package: "swift-grammar"),
             ]),

Package.swift

@@ -1,6 +1,6 @@
 <div align="center">
 
-<strong><em><code>unidoc</code></em></strong><br><small><code>0.2.3</code></small>
+<strong><em><code>unidoc</code></em></strong><br><small><code>0.2.4</code></small>
 
 [![ci build status](https://github.com/kelvin13/swift-unidoc/actions/workflows/build.yml/badge.svg)](https://github.com/kelvin13/swift-unidoc/actions/workflows/build.yml)
 
@@ -104,6 +104,8 @@ Unidoc is tightly-integrated with Swiftinit, but you can run it locally to previ
 
 Unidoc uses [MongoDB](https://www.mongodb.com/) to persist documentation. This allows for fast startup times as Unidoc performs almost no initialization, but requires you to have an active MongoDB replica set running on your local machine. See [`Testing.md`](Guides/Testing.md) for instructions on setting up a local environment.
 
+Unidoc uses HTTPS everywhere. See [`GeneratingCertificates.md`](Guides/GeneratingCertificates.md) for how to generate a local and certificate and certificate authority for `localhost`.
+
 TODO: Add example for running the Unidoc server locally.
 
 TODO: Add example for invoking the Unidoc compiler.

README.md

@@ -1,13 +1,19 @@
+import NIOSSL
+
 @frozen public
 struct Localhost:ServerAuthority
 {
-    @inlinable internal
-    init()
+    public
+    let tls:NIOSSLContext
+
+    @inlinable public
+    init(tls:NIOSSLContext)
     {
+        self.tls = tls
     }
 
     @inlinable public static
-    var scheme:ServerScheme { .http }
+    var scheme:ServerScheme { .https }
     @inlinable public static
     var domain:String { "127.0.0.1" }
 }

Sources/HTTPServer/Authorities/Localhost.swift

@@ -2,34 +2,24 @@ import HTML
 import NIOCore
 import NIOHTTP1
 import NIOPosix
+import NIOSSL
 import TraceableErrors
 
 public
-protocol ServerAuthority<SecurityContext>:Sendable
+protocol ServerAuthority:Sendable
 {
-    associatedtype SecurityContext = Never
-
     static
     var scheme:ServerScheme { get }
     static
     var domain:String { get }
 
-    var tls:SecurityContext? { get }
+    var tls:NIOSSLContext { get }
 
     static
     func redact(error:any Error) -> String
 }
-
-extension ServerAuthority where Self == Localhost
-{
-    @inlinable public static
-    var localhost:Self { .init() }
-}
-
-extension ServerAuthority<Never>
+extension ServerAuthority
 {
-    @inlinable public
-    var tls:SecurityContext? { nil }
     /// Dumps detailed information about the caught error. This information will be shown to
     /// *anyone* accessing the server. In production, we strongly recommend overriding this
     /// default implementation to avoid inadvertently exposing sensitive data via type
@@ -66,8 +56,6 @@ extension ServerAuthority
     {
         switch self.scheme
         {
-        case .http(port: 80):           return "http://\(self.domain)\(uri)"
-        case .http(port: let port):     return "http://\(self.domain):\(port)\(uri)"
         case .https(port: 443):         return "https://\(self.domain)\(uri)"
         case .https(port: let port):    return "https://\(self.domain):\(port)\(uri)"
         }

Sources/HTTPServer/Authorities/ServerAuthority.swift

@@ -2,15 +2,11 @@
 enum ServerScheme
 {
     case https(port:Int = 443)
-    case http(port:Int = 80)
 }
 extension ServerScheme
 {
     @inlinable public static
     var https:Self { .https() }
-
-    @inlinable public static
-    var http:Self { .http() }
 }
 extension ServerScheme
 {
@@ -19,7 +15,6 @@ extension ServerScheme
     {
         switch self
         {
-        case .http(port: let port):     return port
         case .https(port: let port):    return port
         }
     }
@@ -28,7 +23,6 @@ extension ServerScheme
     {
         switch self
         {
-        case .http:             return "http"
         case .https:            return "https"
         }
     }

Sources/HTTPServer/Authorities/ServerScheme.swift

@@ -1,7 +1,7 @@
 import HTTP
 import NIOCore
 import NIOPosix
-import NIOHTTP1
+import NIOHTTP2
 import NIOSSL
 
 public
@@ -30,26 +30,14 @@ extension HTTPServerDelegate
         {
             (channel:any Channel) -> EventLoopFuture<Void> in
 
-            let endpoint:ServerInterfaceHandler<Authority, Self> = .init(
-                address: channel.remoteAddress,
-                server: self)
-
-            guard let tls:NIOSSLContext = authority.tls as? NIOSSLContext
-            else
-            {
-                return channel.pipeline.configureHTTPServerPipeline(withErrorHandling: true)
-                    .flatMap
-                {
-                    channel.pipeline.addHandler(endpoint)
-                }
-            }
-            return  channel.pipeline.addHandler(NIOSSLServerHandler.init(context: tls))
-                    .flatMap
+            channel.pipeline.addHandler(NIOSSLServerHandler.init(context: authority.tls))
+                .flatMap
             {
-                    channel.pipeline.configureHTTPServerPipeline(withErrorHandling: true)
-                    .flatMap
+                channel.configureCommonHTTPServerPipeline
                 {
-                    channel.pipeline.addHandler(endpoint)
+                    $0.pipeline.addHandler(ServerInterfaceHandler<Authority, Self>.init(
+                        address: channel.remoteAddress,
+                        server: self))
                 }
             }
         }

Sources/HTTPServer/Channels/HTTPServerDelegate.swift

@@ -16,14 +16,14 @@ extension SemanticVersion
         }
     }
 
-    @available(*, deprecated, message: "use 'patch' or switch explicitly instead")
+    /// Returns true if this is a release version, false if it is a prerelease.
     @inlinable public
-    var release:PatchVersion?
+    var release:Bool
     {
         switch self
         {
-        case .release(let version, _):  return version
-        case .prerelease:               return nil
+        case .release:      return true
+        case .prerelease:   return false
         }
     }
 }

Sources/SemanticVersions/SemanticVersion.swift

@@ -2,6 +2,7 @@ import BSON
 import GitHubAPI
 import JSONEncoding
 import MongoDB
+import SemanticVersions
 import SHA1
 import UnidocAnalysis
 import UnidocRecords
@@ -107,20 +108,21 @@ extension PackageDatabase.Editions
     public
     func register(_ tag:__owned GitHub.Tag,
         package:Int32,
+        version:SemanticVersion,
         with session:Mongo.Session) async throws -> Int32?
     {
-        //  We use the SHA-1 hash as “proof” that the edition has at least one symbol graph.
-        //  Therefore, merely registering tags does not update hashes.
         let placement:Placement = try await self.register(package: package,
+            version: version,
             refname: tag.name,
-            sha1: nil,
+            sha1: tag.hash,
             with: session)
 
         return placement.new ? placement.coordinate : nil
     }
 
     func register(
         package:Int32,
+        version:SemanticVersion,
         refname:String,
         sha1:SHA1?,
         with session:Mongo.Session) async throws -> Placement
@@ -134,6 +136,8 @@ extension PackageDatabase.Editions
         let edition:PackageEdition = .init(id: .init(
                 package: package,
                 version: placement.coordinate),
+            release: version.release,
+            patch: version.patch,
             name: refname,
             sha1: sha1)
 
@@ -146,24 +150,12 @@ extension PackageDatabase.Editions
         {
             switch placement.sha1
             {
-            case nil:
-                //  If the edition would gain a hash, we should update it.
-
-                //  FIXME: this can race another update, in which case we will store an
-                //  arbitrary choice of hash without marking the edition dirty.
-                //  We should use `placement.sha1` as a hint to skip the update only,
-                //  and set the dirty flag within a custom update statement.
-                try await self.update(some: edition, with: session)
-
             case sha1?:
                 //  Nothing to do.
                 break
 
-            case _?:
-                try await self.update(field: PackageEdition[.lost],
-                    of: edition.id,
-                    to: true,
-                    with: session)
+            case _:
+                try await self.update(some: edition, with: session)
             }
         }
 

Sources/UnidocDB/Packages/PackageDatabase.Editions.swift

@@ -1,6 +1,7 @@
 import GitHubAPI
 import ModuleGraphs
 import MongoDB
+import SemanticVersions
 import SymbolGraphs
 import UnidocAnalysis
 import UnidocLinker
@@ -74,10 +75,12 @@ extension PackageDatabase
 
         let version:Int32
 
-        if  let commit:SymbolGraphMetadata.Commit = docs.metadata.commit
+        if  let commit:SymbolGraphMetadata.Commit = docs.metadata.commit,
+            let semver:SemanticVersion = .init(refname: commit.refname)
         {
             let placement:Editions.Placement = try await self.editions.register(
                 package: placement.coordinate,
+                version: semver,
                 refname: commit.refname,
                 sha1: commit.hash,
                 with: session)
@@ -87,11 +90,21 @@ extension PackageDatabase
         else if case .swift = docs.metadata.package,
             let tagname:String = docs.metadata.commit?.refname
         {
+            //  FIXME: we need a better way to handle this
+            let semver:SemanticVersion
+            switch tagname
+            {
+            case "swift-5.8.1-RELEASE": semver = .release(.v(5, 8, 1))
+            case "swift-5.9-RELEASE":   semver = .release(.v(5, 9, 0))
+            case _:
+                fatalError("unimplemented")
+            }
             /// Standard library symbol graphs don’t come with hashes, so we can’t efficiently
             /// “prove” that a particular edition has at least one symbol graph. But we don’t
             /// need to query that in the first place.
             let placement:Editions.Placement = try await self.editions.register(
                 package: placement.coordinate,
+                version: semver,
                 refname: tagname,
                 sha1: nil,
                 with: session)