Full-Stack Swift with iOS Clients

// Server/Sources/App/FieldNotesModels.swift
import FieldNotesWire
import Fluent
import Foundation
import Vapor

/// One synced note. The id is generated by the client, so the same PUT can be replayed safely.
final class FieldNote: Model, @unchecked Sendable {
    static let schema = "field_notes"

    @ID(custom: .id, generatedBy: .user) var id: UUID?
    @Field(key: "owner_id") var ownerID: UUID
    @Field(key: "title") var title: String
    @Field(key: "body") var body: String
    @Field(key: "created_at") var createdAt: Date
    @Field(key: "client_updated_at") var clientUpdatedAt: Date    // what the device sent: decides who wins a conflict
    @Field(key: "server_updated_at") var serverUpdatedAt: Date    // set by the server: what `since` filters on
    @OptionalField(key: "notebook_id") var notebookID: UUID?
    @Field(key: "tags") var tags: [String]
    @Field(key: "is_pinned") var isPinned: Bool
    @OptionalField(key: "location") var location: NoteLocation?

    init() {}

    init(id: UUID, ownerID: UUID) {
        self.id = id
        self.ownerID = ownerID
    }
}

/// Metadata of one uploaded photo; the bytes live on disk under the attachments directory.
final class NoteAttachment: Model, @unchecked Sendable {
    static let schema = "note_attachments"

    @ID(custom: .id, generatedBy: .user) var id: UUID?
    @Field(key: "owner_id") var ownerID: UUID
    @Field(key: "content_type") var contentType: String
    @Field(key: "byte_count") var byteCount: Int
    @Field(key: "sha256") var sha256: String
    @Timestamp(key: "created_at", on: .create) var createdAt: Date?

    init() {}

    init(id: UUID, ownerID: UUID, contentType: String, byteCount: Int, sha256: String) {
        self.id = id
        self.ownerID = ownerID
        self.contentType = contentType
        self.byteCount = byteCount
        self.sha256 = sha256
    }
}

struct CreateFieldNotes: AsyncMigration {
    func prepare(on database: any Database) async throws {
        try await database.schema("field_notes")
            .field(.id, .uuid, .identifier(auto: false))
            .field("owner_id", .uuid, .required, .references("users", "id", onDelete: .cascade))
            .field("title", .string, .required)
            .field("body", .string, .required)
            .field("created_at", .datetime, .required)
            .field("client_updated_at", .datetime, .required)
            .field("server_updated_at", .datetime, .required)
            .field("notebook_id", .uuid)
            .field("tags", .json, .required)
            .field("is_pinned", .bool, .required)
            .field("location", .json)
            .create()
        try await database.schema("note_attachments")
            .field(.id, .uuid, .identifier(auto: false))
            .field("owner_id", .uuid, .required, .references("users", "id", onDelete: .cascade))
            .field("content_type", .string, .required)
            .field("byte_count", .int, .required)
            .field("sha256", .string, .required)
            .field("created_at", .datetime)
            .create()
    }

    func revert(on database: any Database) async throws {
        try await database.schema("note_attachments").delete()
        try await database.schema("field_notes").delete()
    }
}

// Server/Sources/App/FieldNotesCoding.swift
import FieldNotesWire
import Vapor

extension Request {
    /// Decodes a body with the same snake_case + ISO 8601 coder the clients use.
    func decodeFieldNotes<T: Decodable>(_ type: T.Type) throws -> T {
        try content.decode(type, using: FieldNotesCoding.makeDecoder())
    }

    /// The optional `?since=2026-10-17T10:00:00Z` parameter shared by the list and the change stream.
    func sinceParameter() throws -> Date? {
        guard let raw = query[String.self, at: "since"] else { return nil }
        guard let date = try? Date(raw, strategy: Date.ISO8601FormatStyle()) else {
            throw Abort(.badRequest, reason: "`since` must be an ISO 8601 date such as 2026-10-17T10:00:00Z.")
        }
        return date
    }
}

extension Response {
    /// A JSON response encoded with the FieldNotes coder instead of the application's global one.
    static func fieldNotes<T: Encodable>(_ value: T, status: HTTPStatus = .ok) throws -> Response {
        let response = Response(status: status)
        try response.content.encode(value, using: FieldNotesCoding.makeEncoder())
        return response
    }
}

extension FieldNote {
    func toRemote() -> RemoteNote {
        RemoteNote(id: id!, title: title, body: body, createdAt: createdAt, updatedAt: serverUpdatedAt,
                   notebookID: notebookID, tags: tags, isPinned: isPinned, location: location)
    }

    /// Is the content the same, ignoring the timestamps? Used to recognise a replayed request.
    func hasSameContent(as note: RemoteNote) -> Bool {
        title == note.title && body == note.body && createdAt == note.createdAt && notebookID == note.notebookID
            && tags == note.tags && isPinned == note.isPinned && location == note.location
    }

    func apply(_ note: RemoteNote, now: Date) {
        title = note.title
        body = note.body
        createdAt = note.createdAt
        clientUpdatedAt = note.updatedAt
        serverUpdatedAt = now
        notebookID = note.notebookID
        tags = note.tags
        isPinned = note.isPinned
        location = note.location
    }
}

extension RemoteNote {
    /// A reason the note cannot be stored, or nil. Limits keep one client from filling the table.
    var validationProblem: String? {
        if title.isEmpty || title.count > 200 { return "title must be 1 to 200 characters" }
        if body.utf8.count > 100_000 { return "body must be at most 100000 bytes" }
        if tags.count > 32 || tags.contains(where: { $0.isEmpty || $0.count > 50 }) { return "tags: at most 32 of 1 to 50 characters" }
        if let location, !(-90...90).contains(location.latitude) || !(-180...180).contains(location.longitude) {
            return "location is out of range"
        }
        return nil
    }
}

// Server/Sources/App/RetryAfterMiddleware.swift
import Vapor

/// A fixed-window counter per key. Pure state, so it can be tested without a server.
actor FixedWindowLimiter {
    private let limit: Int
    private let window: TimeInterval
    private var windows: [String: (start: Date, count: Int)] = [:]

    init(limit: Int, window: TimeInterval) {
        self.limit = limit
        self.window = window
    }

    /// Returns nil when the request may proceed, or the whole seconds to wait before the window reopens.
    func hit(_ key: String, now: Date = Date()) -> Int? {
        if windows.count > 10_000 { windows = windows.filter { now.timeIntervalSince($0.value.start) < window } }
        var entry = windows[key] ?? (start: now, count: 0)
        if now.timeIntervalSince(entry.start) >= window { entry = (start: now, count: 0) }
        entry.count += 1
        windows[key] = entry
        guard entry.count > limit else { return nil }
        return max(1, Int((window - now.timeIntervalSince(entry.start)).rounded(.up)))
    }
}

struct RateLimitMiddleware: AsyncMiddleware {
    let limiter: FixedWindowLimiter

    func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
        let key = request.remoteAddress?.ipAddress ?? "unknown"
        if let wait = await limiter.hit(key) {
            throw Abort(.tooManyRequests, headers: ["Retry-After": String(wait)], reason: "Too many requests.")
        }
        return try await next.respond(to: request)
    }
}

/// While `maintenanceRetryAfter` is set, every `/v1` request is refused with 503 and a Retry-After in seconds.
struct MaintenanceMiddleware: AsyncMiddleware {
    func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
        if let seconds = request.application.fieldNotes.maintenanceRetryAfter {
            throw Abort(.serviceUnavailable, headers: ["Retry-After": String(seconds)], reason: "Down for maintenance.")
        }
        return try await next.respond(to: request)
    }
}

// Server/Sources/App/ChangeHub.swift
import FieldNotesWire
import Vapor

/// Fans changed notes out to every open `/v1/notes/changes` stream of the same owner.
actor ChangeHub {
    enum Event: Sendable {
        case note(RemoteNote)
        case heartbeat
    }

    private var subscribers: [UUID: (owner: UUID, continuation: AsyncStream<Event>.Continuation)] = [:]

    var subscriberCount: Int { subscribers.count }

    func subscribe(owner: UUID) -> (token: UUID, events: AsyncStream<Event>) {
        let token = UUID()
        let (events, continuation) = AsyncStream.makeStream(of: Event.self, bufferingPolicy: .bufferingNewest(1_000))
        subscribers[token] = (owner, continuation)
        return (token, events)
    }

    func unsubscribe(_ token: UUID) {
        subscribers.removeValue(forKey: token)?.continuation.finish()
    }

    func publish(_ notes: [RemoteNote], owner: UUID) {
        for subscriber in subscribers.values where subscriber.owner == owner {
            for note in notes { subscriber.continuation.yield(.note(note)) }
        }
    }

    func heartbeat(_ token: UUID) {
        subscribers[token]?.continuation.yield(.heartbeat)
    }

    /// Called on shutdown so every stream ends and its connection closes.
    func finishAll() {
        for subscriber in subscribers.values { subscriber.continuation.finish() }
        subscribers.removeAll()
    }
}

struct ChangeHubKey: StorageKey { typealias Value = ChangeHub }

struct FieldNotesSettings: Sendable {
    /// Set while the service is in maintenance: `/status` reports it and `/v1` answers 503 with this Retry-After.
    var maintenanceRetryAfter: Int?
    /// How long one `/v1/notes/changes` response stays open before the server ends it.
    var streamLifetime: Duration = .seconds(55)
    var heartbeatInterval: Duration = .seconds(15)
    var attachmentsDirectory: String
}

struct FieldNotesSettingsKey: StorageKey { typealias Value = FieldNotesSettings }

extension Application {
    var changeHub: ChangeHub {
        get { storage[ChangeHubKey.self]! }
        set { storage[ChangeHubKey.self] = newValue }
    }

    var fieldNotes: FieldNotesSettings {
        get { storage[FieldNotesSettingsKey.self]! }
        set { storage[FieldNotesSettingsKey.self] = newValue }
    }
}

struct ChangeHubShutdown: LifecycleHandler {
    func shutdownAsync(_ application: Application) async {
        await application.changeHub.finishAll()
    }
}

// Server/Sources/App/FieldNotesRoutes.swift
import FieldNotesWire
import Fluent
import Foundation
import Vapor

struct FieldNotesController: RouteCollection {
    static let maxBatch = 100

    let limiter: FixedWindowLimiter

    func boot(routes: any RoutesBuilder) throws {
        // Public: no token, no rate limit, so a client can always ask whether the service is up.
        routes.get("status", use: status)

        let v1 = routes.grouped("v1")
            .grouped(MaintenanceMiddleware(), RateLimitMiddleware(limiter: limiter))
            .grouped(HashedTokenAuthenticator())
            .grouped(UserToken.guardMiddleware(throwing: Abort(
                .unauthorized,
                headers: ["WWW-Authenticate": "Bearer realm=\"fieldnotes\""],
                reason: "Missing, expired or revoked token."
            )))

        v1.get("notes", use: list)
        v1.put("notes", use: put)
        v1.get("notes", "changes", use: changes)
    }

    @Sendable func status(req: Request) throws -> Response {
        let retry = req.application.fieldNotes.maintenanceRetryAfter
        let status = ServiceStatus(isAvailable: retry == nil, message: retry.map { _ in "Down for maintenance." })
        let response = try Response.fieldNotes(status)
        response.headers.replaceOrAdd(name: .cacheControl, value: "no-store")
        return response
    }

    /// GET /v1/notes?since=: the caller's notes changed at or after `since`, oldest first.
    @Sendable func list(req: Request) async throws -> Response {
        let owner = try req.auth.require(User.self).requireID()
        let notes = try await Self.changed(since: try req.sinceParameter(), owner: owner, on: req.db, limit: 1_000)
        return try .fieldNotes(notes)
    }

    static func changed(since: Date?, owner: UUID, on db: any Database, limit: Int) async throws -> [RemoteNote] {
        var query = FieldNote.query(on: db).filter(\.$ownerID == owner)
        if let since { query = query.filter(\.$serverUpdatedAt >= since) }
        return try await query.sort(\.$serverUpdatedAt, .ascending).limit(limit).all().map { $0.toRemote() }
    }

    /// PUT /v1/notes: create or replace a batch. Idempotent: replaying the same body changes nothing.
    @Sendable func put(req: Request) async throws -> HTTPStatus {
        let owner = try req.auth.require(User.self).requireID()
        let batch = try req.decodeFieldNotes([RemoteNote].self)
        guard batch.count <= Self.maxBatch else {
            throw Abort(.payloadTooLarge, reason: "At most \(Self.maxBatch) notes per request.")
        }
        for note in batch {
            if let problem = note.validationProblem { throw Abort(.unprocessableEntity, reason: "Note \(note.id): \(problem).") }
        }
        let now = Date()
        let changed = try await req.db.transaction { db -> [RemoteNote] in
            var changed: [RemoteNote] = []
            for incoming in batch {
                let stored: FieldNote
                if let existing = try await FieldNote.find(incoming.id, on: db) {
                    guard existing.ownerID == owner else { throw Abort(.forbidden, reason: "That note id belongs to someone else.") }
                    if incoming.updatedAt < existing.clientUpdatedAt { continue }                      // stale: the server copy is newer
                    if incoming.updatedAt == existing.clientUpdatedAt, existing.hasSameContent(as: incoming) { continue }   // replay
                    stored = existing
                } else {
                    stored = FieldNote(id: incoming.id, ownerID: owner)
                }
                stored.apply(incoming, now: now)
                try await stored.save(on: db)
                changed.append(stored.toRemote())
            }
            return changed
        }
        await req.application.changeHub.publish(changed, owner: owner)
        return .noContent
    }

    /// One note, encoded, followed by a line feed.
    static func ndjsonLine(_ note: RemoteNote, using encoder: JSONEncoder) throws -> ByteBuffer {
        var buffer = ByteBuffer(bytes: try encoder.encode(note))
        buffer.writeInteger(UInt8(ascii: "\n"))
        return buffer
    }

    /// GET /v1/notes/changes: NDJSON, one RemoteNote per line, a blank line as heartbeat, closed after `streamLifetime`.
    @Sendable func changes(req: Request) async throws -> Response {
        let owner = try req.auth.require(User.self).requireID()
        let since = try req.sinceParameter()
        let hub = req.application.changeHub
        let settings = req.application.fieldNotes
        let encoder = FieldNotesCoding.makeEncoder()
        let db = req.db

        // Subscribe BEFORE reading the backlog, so a note saved in between is delivered twice rather than never.
        let (token, events) = await hub.subscribe(owner: owner)
        let backlog: [RemoteNote]
        do {
            backlog = try await Self.changed(since: since, owner: owner, on: db, limit: 1_000)
        } catch {
            await hub.unsubscribe(token)
            throw error
        }

        var headers = HTTPHeaders()
        headers.contentType = HTTPMediaType(type: "application", subType: "x-ndjson", parameters: ["charset": "utf-8"])
        headers.replaceOrAdd(name: .cacheControl, value: "no-store")
        headers.replaceOrAdd(name: "X-Accel-Buffering", value: "no")   // nginx: do not buffer this response
        let body = Response.Body(managedAsyncStream: { writer in
            let ticker = Task {
                while !Task.isCancelled {
                    try await Task.sleep(for: settings.heartbeatInterval)
                    await hub.heartbeat(token)
                }
            }
            let deadline = Task {
                try await Task.sleep(for: settings.streamLifetime)
                await hub.unsubscribe(token)          // ends `events`, so the loop below returns and Vapor closes the body
            }
            defer {
                ticker.cancel()
                deadline.cancel()
                Task { await hub.unsubscribe(token) }
            }
            for note in backlog {
                try await writer.writeBuffer(try Self.ndjsonLine(note, using: encoder))
            }
            for await event in events {
                switch event {
                case .note(let note):
                    try await writer.writeBuffer(try Self.ndjsonLine(note, using: encoder))
                case .heartbeat:
                    try await writer.writeBuffer(ByteBuffer(string: "\n"))
                }
            }
        })
        return Response(status: .ok, headers: headers, body: body)
    }
}

// Server/Sources/App/AttachmentRoutes.swift
import Crypto
import Fluent
import Foundation
import Vapor
import _NIOFileSystem

struct AttachmentController: RouteCollection {
    static let maxBytes = 20 * 1024 * 1024
    static let allowedTypes: Set<String> = ["image/jpeg", "image/png", "image/heic"]

    let limiter: FixedWindowLimiter

    func boot(routes: any RoutesBuilder) throws {
        let v1 = routes.grouped("v1")
            .grouped(MaintenanceMiddleware(), RateLimitMiddleware(limiter: limiter))
            .grouped(HashedTokenAuthenticator())
            .grouped(UserToken.guardMiddleware(throwing: Abort(
                .unauthorized,
                headers: ["WWW-Authenticate": "Bearer realm=\"fieldnotes\""],
                reason: "Missing, expired or revoked token."
            )))

        v1.get("attachments", ":id", use: download)
        // The body is streamed to disk, never collected in memory.
        v1.on(.PUT, "attachments", ":id", body: .stream, use: upload)
    }

    private func attachmentID(_ req: Request) throws -> UUID {
        guard let id = req.parameters.get("id", as: UUID.self) else { throw Abort(.badRequest, reason: "Invalid attachment id.") }
        return id
    }

    /// Server-made path only: the client supplies a UUID, never a file name.
    private func path(for id: UUID, owner: UUID, in directory: String) -> String {
        "\(directory)/\(owner.uuidString.lowercased())/\(id.uuidString.lowercased())"
    }

    /// GET /v1/attachments/{id}: ETag, If-None-Match and Range are handled by `asyncStreamFile`.
    @Sendable func download(req: Request) async throws -> Response {
        let owner = try req.auth.require(User.self).requireID()
        let id = try attachmentID(req)
        guard let attachment = try await NoteAttachment.query(on: req.db)
            .filter(\.$id == id).filter(\.$ownerID == owner).first()
        else { throw Abort(.notFound) }
        let directory = req.application.fieldNotes.attachmentsDirectory
        let response = try await req.fileio.asyncStreamFile(at: path(for: id, owner: owner, in: directory))
        response.headers.replaceOrAdd(name: .contentType, value: attachment.contentType)
        response.headers.replaceOrAdd(name: "X-Content-Type-Options", value: "nosniff")
        response.headers.replaceOrAdd(name: .cacheControl, value: "private, max-age=0, must-revalidate")
        return response
    }

    /// PUT /v1/attachments/{id}: idempotent, the same id replaces the same file.
    @Sendable func upload(req: Request) async throws -> HTTPStatus {
        let owner = try req.auth.require(User.self).requireID()
        let id = try attachmentID(req)
        guard let type = req.headers.contentType?.serialize(), Self.allowedTypes.contains(type) else {
            throw Abort(.unsupportedMediaType, reason: "Allowed types: \(Self.allowedTypes.sorted().joined(separator: ", ")).")
        }
        if let length = req.headers.first(name: .contentLength).flatMap(Int.init), length > Self.maxBytes {
            throw Abort(.payloadTooLarge)
        }
        if let existing = try await NoteAttachment.find(id, on: req.db), existing.ownerID != owner { throw Abort(.forbidden) }

        let directory = req.application.fieldNotes.attachmentsDirectory
        let finalPath = path(for: id, owner: owner, in: directory)
        let partialPath = finalPath + ".part"
        try await FileSystem.shared.createDirectory(at: FilePath("\(directory)/\(owner.uuidString.lowercased())"),
                                                    withIntermediateDirectories: true)
        let handle = try await FileSystem.shared.openFile(forWritingAt: FilePath(partialPath), options: .newFile(replaceExisting: true))
        var hasher = SHA256()
        var offset: Int64 = 0
        do {
            for try await chunk in req.body {
                offset += Int64(chunk.readableBytes)
                guard offset <= Int64(Self.maxBytes) else { throw Abort(.payloadTooLarge) }
                hasher.update(data: chunk.readableBytesView)
                try await handle.write(contentsOf: chunk, toAbsoluteOffset: offset - Int64(chunk.readableBytes))
            }
            try await handle.close()
        } catch {
            _ = try? await handle.close()
            _ = try? await FileSystem.shared.removeItem(at: FilePath(partialPath))
            throw error
        }
        // Atomically swaps the finished file in, whether or not an earlier upload with this id exists.
        try await FileSystem.shared.replaceItem(at: FilePath(finalPath), withItemAt: FilePath(partialPath))

        let digest = hasher.finalize().map { String(format: "%02x", $0) }.joined()
        let row = try await NoteAttachment.find(id, on: req.db) ?? NoteAttachment(id: id, ownerID: owner, contentType: type,
                                                                                  byteCount: Int(offset), sha256: digest)
        row.contentType = type
        row.byteCount = Int(offset)
        row.sha256 = digest
        try await row.save(on: req.db)
        return .noContent
    }
}

// Server/Sources/App/configure.swift
import Fluent
import FluentSQLiteDriver
import Vapor

func configure(_ app: Application) async throws {
    app.databases.use(.sqlite(.memory), as: .sqlite)
    app.passwords.use(.bcrypt(cost: app.environment == .testing ? 4 : 12))
    app.migrations.add(CreateBookshelf(), CreateUserToken(), CreateFieldNotes())

    app.changeHub = ChangeHub()
    app.lifecycle.use(ChangeHubShutdown())
    app.fieldNotes = FieldNotesSettings(
        maintenanceRetryAfter: Environment.get("FIELDNOTES_MAINTENANCE_RETRY_AFTER").flatMap(Int.init),
        attachmentsDirectory: Environment.get("ATTACHMENTS_DIR") ?? app.directory.workingDirectory + "Storage/attachments"
    )

    if let seconds = Environment.get("FIELDNOTES_STREAM_SECONDS").flatMap(Int.init) { app.fieldNotes.streamLifetime = .seconds(seconds) }
    if let seconds = Environment.get("FIELDNOTES_HEARTBEAT_SECONDS").flatMap(Int.init) { app.fieldNotes.heartbeatInterval = .seconds(seconds) }

    let limiter = FixedWindowLimiter(limit: 120, window: 60)
    try app.register(collection: AuthController())
    try app.register(collection: BooksController())
    try app.register(collection: FieldNotesController(limiter: limiter))
    try app.register(collection: AttachmentController(limiter: limiter))
    try await app.autoMigrate()
}

ATTACHMENTS_DIR=/tmp/fn-att swift run App serve --hostname 127.0.0.1 --port 8089
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/register -H 'content-type: application/json' \
  -d '{"email":"ada@example.com","password":"correct horse battery"}'
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/token -u 'ada@example.com:correct horse battery'

{"id":"83EA48A2-9CF8-46FB-9EE6-6C2D1E9A0F35","email":"ada@example.com","role":"reader"}
{"token":"bk_...","expiresAt":"2026-10-17T18:31:30Z"}

curl -s -i http://127.0.0.1:8089/status
curl -s -i http://127.0.0.1:8089/v1/notes

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
cache-control: no-store

{"is_available":true}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="fieldnotes"
content-type: application/json; charset=utf-8

{"error":true,"reason":"Missing, expired or revoked token."}

curl -s -i -X PUT http://127.0.0.1:8089/v1/notes -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '[{"id":"6f1d1c9e-1111-4a3b-9c2d-0a1b2c3d4e5f","title":"Beetle traps, site A","body":"Checked 12 traps.","created_at":"2026-10-17T08:00:00Z","updated_at":"2026-10-17T08:05:00Z","tags":["field","beetles"],"is_pinned":false,"location":{"latitude":42.8,"longitude":-1.64,"place_name":"Site A"}}]'
curl -s http://127.0.0.1:8089/v1/notes -H "Authorization: Bearer $TOKEN"

HTTP/1.1 204 No Content

[{"title":"Beetle traps, site A","location":{"place_name":"Site A","latitude":42.8,"longitude":-1.64},"tags":["field","beetles"],"body":"Checked 12 traps.","created_at":"2026-10-17T08:00:00Z","id":"6F1D1C9E-1111-4A3B-9C2D-0A1B2C3D4E5F","updated_at":"2026-10-17T17:28:44Z","is_pinned":false}]

curl -s -N "http://127.0.0.1:8089/v1/notes/changes?since=2100-01-01T00:00:00Z" -H "Authorization: Bearer $TOKEN" > stream.out
# two seconds later, from another terminal: PUT /v1/notes with the same id and updated_at 08:09:00Z
cat -vet stream.out

{"title":"Beetle traps, site A (revised)","tags":["field"],"body":"Checked 12 traps.","created_at":"2026-10-17T08:00:00Z","id":"6F1D1C9E-1111-4A3B-9C2D-0A1B2C3D4E5F","updated_at":"2026-10-17T17:28:46Z","is_pinned":true}$
$
$

curl -s -i -X PUT $B/v1/attachments/$ID -H "Authorization: Bearer $TOKEN" -H 'content-type: image/jpeg' --data-binary @photo.jpg
curl -s -D - -o photo.out $B/v1/attachments/$ID -H "Authorization: Bearer $TOKEN"
curl -s -i $B/v1/attachments/$ID -H "Authorization: Bearer $TOKEN" -H "If-None-Match: $ETAG"
curl -s -D - -o part.out $B/v1/attachments/$ID -H "Authorization: Bearer $TOKEN" -H 'Range: bytes=0-99'

HTTP/1.1 204 No Content

HTTP/1.1 200 OK
last-modified: Sat, 17 Oct 2026 17:31:13 GMT
etag: "1792258273-3000"
accept-ranges: bytes
content-length: 3000
content-type: image/jpeg
X-Content-Type-Options: nosniff
cache-control: private, max-age=0, must-revalidate

HTTP/1.1 304 Not Modified
etag: "1792258273-3000"

HTTP/1.1 206 Partial Content
accept-ranges: bytes
content-range: bytes 0-99/3000
content-length: 100
content-type: image/jpeg

 114 200
  11 429

HTTP/1.1 429 Too Many Requests
Retry-After: 59
content-type: application/json; charset=utf-8

{"error":true,"reason":"Too many requests."}

// Server/Tests/AppTests/FieldNotesTests.swift (excerpt)
@Test func putIsIdempotentAndListReturnsServerTimestamps() async throws {
    try await withApp { app in
        let bearer = try await token(app, email: "ada@example.com")
        let first = note()
        let status = try await put(app, [first], token: bearer)
        #expect(status == .noContent)
        let stored = try await list(app, token: bearer)
        #expect(stored.count == 1)

        // Replaying the identical request changes nothing, including the server timestamp.
        try await Task.sleep(for: .milliseconds(1_100))
        _ = try await put(app, [first], token: bearer)
        let replayed = try await list(app, token: bearer)
        #expect(replayed == stored)
    }
}

@Test func staleWritesLoseAndNewerWritesWin() async throws {
    try await withApp { app in
        let bearer = try await token(app, email: "ada@example.com")
        let id = UUID()
        _ = try await put(app, [note(id, title: "v2", at: 1_700_000_200)], token: bearer)
        _ = try await put(app, [note(id, title: "v1 (older)", at: 1_700_000_100)], token: bearer)
        let afterStale = try await list(app, token: bearer)
        #expect(afterStale.first?.title == "v2")
    }
}

// Apple/Sources/App/AppStoreNotifications.swift
import AppStoreServerLibrary
import Foundation
import Vapor

/// The body Apple POSTs to your server for App Store Server Notifications V2.
struct SignedPayloadBody: Content {
    var signedPayload: String
}

struct AppStoreVerifierKey: StorageKey { typealias Value = SignedDataVerifier }

extension Application {
    var appStoreVerifier: SignedDataVerifier? {
        get { storage[AppStoreVerifierKey.self] }
        set { storage[AppStoreVerifierKey.self] = newValue }
    }
}

enum AppStoreSetup {
    /// Loads Apple's root certificates (the .cer files from https://www.apple.com/certificateauthority/) from a directory.
    static func makeVerifier(rootsDirectory: String, bundleID: String, appAppleID: Int64?,
                             environment: AppStoreEnvironment) throws -> SignedDataVerifier {
        let roots = try FileManager.default.contentsOfDirectory(atPath: rootsDirectory)
            .filter { $0.hasSuffix(".cer") }
            .map { try Data(contentsOf: URL(fileURLWithPath: rootsDirectory).appending(path: $0)) }
        return try SignedDataVerifier(rootCertificates: roots, bundleId: bundleID, appAppleId: appAppleID,
                                      environment: environment, enableOnlineChecks: true)
    }
}

struct AppStoreNotificationsController: RouteCollection {
    func boot(routes: any RoutesBuilder) throws {
        routes.post("apple", "app-store-notifications", use: receive)
    }

    @Sendable func receive(req: Request) async throws -> HTTPStatus {
        guard let verifier = req.application.appStoreVerifier else { throw Abort(.serviceUnavailable) }
        let body = try req.content.decode(SignedPayloadBody.self)
        switch await verifier.verifyAndDecodeNotification(signedPayload: body.signedPayload) {
        case .valid(let payload):
            // notificationUUID is unique per notification: store it and ignore a repeat, because Apple retries.
            req.logger.info("App Store notification", metadata: [
                "type": "\(payload.rawNotificationType ?? "?")",
                "subtype": "\(payload.rawSubtype ?? "-")",
                "uuid": "\(payload.notificationUUID ?? "?")",
            ])
            if let signedTransaction = payload.data?.signedTransactionInfo,
               case .valid(let transaction) = await verifier.verifyAndDecodeTransaction(signedTransaction: signedTransaction) {
                req.logger.info("Transaction", metadata: [
                    "originalTransactionId": "\(transaction.originalTransactionId ?? "?")",
                    "productId": "\(transaction.productId ?? "?")",
                ])
                // Look the account up by transaction.appAccountToken, then grant or revoke the entitlement.
            }
            return .ok
        case .invalid(.RETRYABLE_VERIFICATION_FAILURE):
            throw Abort(.internalServerError)       // Apple retries on a 5xx; the certificate check could not reach its CRL/OCSP
        case .invalid:
            throw Abort(.badRequest, reason: "Invalid signedPayload.")   // not from Apple, or for another app or environment
        }
    }
}

// Apple/Sources/App/AppAttestChallenges.swift
import Crypto
import Foundation
import Vapor

struct AttestChallenge: Content {
    var challenge: String        // base64, 32 random bytes
    var expiresIn: Int           // seconds
}

struct AppAttestController: RouteCollection {
    static let lifetime: CacheExpirationTime = .seconds(300)

    func boot(routes: any RoutesBuilder) throws {
        routes.get("v1", "attest", "challenge", use: challenge)
    }

    /// Issues a single-use challenge. The device hashes it into the clientDataHash it passes to DeviceCheck.
    @Sendable func challenge(req: Request) async throws -> AttestChallenge {
        let bytes = [UInt8].random(count: 32)
        let value = Data(bytes).base64EncodedString()
        try await req.cache.set("attest:\(value)", to: "issued", expiresIn: Self.lifetime)
        return AttestChallenge(challenge: value, expiresIn: 300)
    }
}

extension Request {
    /// Consumes a challenge: true once, false for an unknown, expired or already used challenge.
    func consumeAttestChallenge(_ value: String) async throws -> Bool {
        let key = "attest:\(value)"
        guard try await cache.get(key, as: String.self) != nil else { return false }
        try await cache.delete(key)
        return true
    }
}