kean.blog

Claude Code Experience

Mon, 23 Jun 2025 14:00:00 +0000

There’s a lot of anxiety around AI coding, but what people often fear is uncertainty. The best way to address it is through action. These tools aren’t going away, so I decided to give one of the latest ones a fair shot this week.

I’ve been using Claude chats for a while, but tools like Cursor never clicked for me. I just didn’t want to introduce a separate IDE into my workflow, and I didn’t feel they offered enough value for an experienced engineer. That changed with Claude Code.

Getting Started

Claude Code is an agentic coding assistant that runs in a terminal and can research your codebase without manual context selection and make coordinated changes across files automatically. It can use command line tools (like git) and MCP servers (like GitHub) to extend its capabilities.

I tried Claude Code when it launched a few months ago and was immediately drawn to its terminal-based interface. I’ve never been a fan of similar products that required you to learn a separate IDE. Claude Code works alongside Xcode and feels like a natural extension of my current workflow.

Unfortunately, the initial version only had a pay-per-token model where costs ramp up quickly. I tried it a few times, but that was it. But now it’s included in the Claude subscription. I upgraded to a Max monthly plan and started exploring without worrying about costs.

I began by watching the video about mastering Claude Code from Boris Cherny, its creator. It was extremely helpful and showed me that I had a lot to learn. I’ve read the bare minimum of the official documentation and started exploring what it can do.

Asking Questions

Following Boris’s recommendation, I started by asking questions about the codebase. Claude can explore your project and answer questions, but don’t take its responses at face value. I currently work on the WordPress iOS apps, which are open-source, and when I asked about post syncing conflicts, it mentioned “collaborative editing” which our app doesn’t support. See the full interaction here.

That’s OK though. I didn’t install it for Q&A.

Writing Code

Starting Small: Refactoring

I had this unused method sitting in one of my files, so I asked: “Remove unused code from this file @file_path”. It worked correctly, though not particularly fast. I opened PR #24590. Definitely not the most efficient use of AI, but hey, it made the right changes.

My next attempt was more ambitious. I asked Claude to rewrite the entire Objective-C “Support Logs” screen using SwiftUI. Here’s the PR #24591. It’s a simple screen with low stakes, and my brief prompt worked. While it didn’t match my coding style perfectly, I manually corrected it.

Feature: Activity Logs and Backups

Now confident, I tackled a large planned project: implementing new “Activity Logs” and “Backups” screens in SwiftUI using the refreshed WordPress design system. This is where things got interesting.

I created a small standalone app target (PR #24598) to iterate quickly while still being able to access all the app dependencies. I asked Claude to generate code based on the previous implementation but with a new design based on the screenshot of a different screen I dropped in the terminal.

It generated code, but it ignored our coding standards. That’s when it hit me. While Claude can explore your project automatically by reading files and running bash commands, it starts from zero every time unless you pre-configure it using CLAUDE.md. Think of it as Claude’s onboarding document. The better you write it, the better code Claude writes for you.

You can generate a CLAUDE.md file using /init. The file should include coding standards, project structure, common patterns, and any domain-specific knowledge. The goal is to update it regularly as you discover what Claude needs to know. This file is part of CLAUDE.md memory management with a few more tools at your disposal.

With an improved CLAUDE.md, I regenerated the code with much better results. If Claude isn’t generating what you want, your prompt is likely underspecified.

To review changes, I asked Claude to generate previews. Claude generated tons of mocks and code with perfect accuracy, nearly instantly, using realistic domain data. It even knew to use actual WordPress terminology. This is where LLMs truly shine.

I continued iterating, opening multiple PRs resulting in this feature branch: PR #24597. It has +3,672 −4,967 changes with around 90% generated by prompts. I even used Claude Code to create commits by simply asking “commit”.

Prototyping

The next day, a colleague had a couple of questions about how WKWebView interacts with the keyboard and whether the app has any control over it. I asked Claude to generate a sample project with an HTML form and add keyboard observers in Swift code. It did so instantly. This is another area where it excels. Normally, I wouldn’t bother – too time-consuming. Now I can verify anything using prototypes instantly, a massive productivity unlock.

My Workflow

I started with short one-liner prompts, with predictably poor results. After a week of trial and error, my workflow evolved to:

Start a new Claude session (/clear)
Ask it to read files I’ll work on and any related files. Pass related screenshots or documents¹.
(Optional) Switch to the “Plan” mode (⇧Tab)
Request the changes (e.g., “rewrite this” or “generate that”) and maybe throw an “ultrathink” at it²
Iterate on the plan
Switch to “Auto-Accept Edits” mode (⇧Tab) and execute
Review changes and iterate until you are satisfied with the results

I typically make one change at a time for easier review. Claude is more accurate with focused tasks. Asking it to do too much usually fails as it makes too many assumptions that can be hard to correct later. Even with detailed prompts, expect multiple iterations. It rarely one-shots changes unless the changes themselves aren’t very specific like generating mock data.

I often skip the planning, especially for small changes. As you get more experienced with Claude, you are more likely to generate what you want on the first plan. There doesn’t seem to be that much science around prompts. For me, as long as you include some relevant details, it works fine. Don’t overthink it.

One limitation: Claude 4 models have a 200K token context window. It’s decent for daily use but can’t process entire projects, so keep your context focused. If it overflows, Claude automatically compacts it, which works but takes time.

Where Claude Code Excels

LLMs excel at generating text (including code):

Generating unit tests
Creating mock data and previews
Anonymizing production data
Refactoring existing code
Prototyping with sample projects
Generating documentation
Summarizing changes for commits, PRs, and release notes

Where It Struggles

Making a large number of small changes across the entire project
Working with newest APIs that the model doesn’t know about yet
Tasks requiring genuine reasoning

As Apple has shown, AI can’t actually reason – it’s all statistics under the hood. This shows in practice as it occasionally makes nonsensical changes or continuously walks down paths that are obvious dead-ends.

For an example of small changes, if you ask to rename a class, it spawns an agent to search for usage and read individual files, taking minutes for what should be instant. In one case, it took 25 minutes to rename EmptyStateView across 137 occurrences in 41 files, while also making unnecessary changes like renaming unrelated methods. Here’s the full session. The workaround? Ask Claude to generate and run a script instead, which is surprisingly effective³.

The amount of time certain operations take is a limiting factor, but it depends on what you ask it to do. It’s the art of writing optimal prompts that you know it can execute well. The other option is parallelization. I currently work interactively with Claude Code, making changes one at a time, as it makes it easier to review the code and it just requires too much steering. But I can see myself parallelizing the work using git worktrees, a recommended approach, and spawning additional Claude sessions to work on other tickets in parallel, particularly bug fixes or other small tasks that can be tested with unit tests and don’t require a long review or a lot of steering.

One thing worth mentioning is the security and privacy considerations. If you are working on sensitive codebases or in regulated industries, you should think twice before deciding whether to use these tools and how.

Productivity Gains

Let’s talk numbers. Last week, I opened these PRs:

That’s +4,263 lines and −6,018 lines of real code changes in my typical coding style and with a high level of quality. In a normal week, I’d manually write maybe 1-2K lines of meaningful changes. And this was my first week seriously using Claude Code, so I wasn’t effective and I spent half the time learning best practices.

Your mileage may vary, but for common tasks, I’m easily 2x more productive. It unlocks changes I’d never make manually: comprehensive unit tests, documentation, elaborate SwiftUI previews. For these specific tasks, it provides potentially infinite productivity gains – generating in seconds what you would never otherwise even attempt to write. Of course, measuring overall productivity is impossible since software engineering involves much more than writing code, but the impact is there.

I’m especially looking forward to sharing the workflows I learned with a team so we could all take advantage of the Claude instances configured to have the same idea of how to write code.

Final Thoughts

Disclosure: I wrote the entire article myself and then used Claude Code as my editor. It underwent multiple iterations, with Claude reviewing the article according to my stated target audience and goals. The thoughts are my own.

After a week with Claude Code, I’m convinced. It’s not about replacing programmers – it’s about amplifying them. The better you are at coding and communicating, the bigger the multiplier⁴. It’s still a tool that requires time and skill to master, with plenty of room for learning and min-maxing.

Claude Code works best when you’re already an expert who knows what to build and how. It turns the boring parts like writing boilerplate, unit tests, documentation into quick prompts. It also surprises you with novel approaches. I learned more this week than my typical one⁵.

For junior developers, these tools present both opportunity and risk – they can accelerate learning by showing patterns and approaches, but there’s danger in accepting generated code without understanding it. The fundamentals still matter.

Some compare AI to the transition from assembly to high-level languages, but I’m not sure that’s accurate. You still write and read the same code. The abstractions haven’t changed. What’s changed is velocity. I can now spend more time on design and architecture instead of mechanical code writing. But that’s only part of the story. The other parts are LLMs used as part of the existing products, with English as a sort of programming language for prompts.

Do I have any concerns about code quality or long-term maintenance implications? In my experience – the opposite. I love the craft of engineering software. Our material is code. With AI, you have the power to effortlessly mold it in any shape or form.

References

Claude can search for context automatically, but doing it yourself is faster and more accurate. When Claude searches on its own, it spawns background agents that can take significant time and often include unrelated content. By explicitly using “Read @file” commands, you give Claude exactly the context it needs. ↩
Special phrases map to thinking levels: “think” < “think hard” < “think harder” < “ultrathink”. These thinking levels actually correspond to different amounts of processing time Claude uses to consider your request. Use higher levels for complex architectural decisions or difficult debugging scenarios. ↩
Even Claude Code itself reveals these limitations. It’s not unlike Guided Generation in new Apple’s Foundation Models where agents combine language models with deterministic tool execution. ↩
It could be famous last words, lol. We don’t know what the future holds. ↩
For example, I learned a pretty cool async/await pattern where you execute Task.sleep inside while !Task.isCancelled to implement polling. ↩

Swift 6

Wed, 17 Jul 2024 14:00:00 +0000

I love using Swift and have no thoughts about switching back to Objective-C, but that’s no longer a conversation because Swift is a de facto language on Apple platforms. During the first few years of Swift, I had complete confidence in its direction, and perhaps it was easier to make every change a slam dunk in the beginning. In recent years, there’ve been some questionable changes, the latest one being Data Race Safety in its current form in Xcode 16 beta.

Problem

If you want to migrate a large codebase to support Swift 6 mode, you need to fix thousands of compiler warnings that become errors once you enable this mode. For example, if you have any global variables, they are now errors.

I think we might need to go back to the drawing board starting from right around here and re-establish what a compiler error is or should be:

A syntax, linker or other error that prevents a compiler from generating the binary
An obvious logic error where the code makes no sense under any circumstances

A compiler can have additional helpful diagnostics and show them as warnings if there is a high chance that the code is incorrect and/or unsafe. That has been my general framework for thinking about what a compiler is, and under that framework, a global variable by itself can’t be an error or a warning.

Data Race Safety is touted as one of the great Swift 6 features. You would expect the compiler to be smart enough to help you automatically find and eliminate the hard-to-debug concurrency issues and code smells, but the reality is quite different with too much of the work shifted to the developer.

OK, this is just for laughs. Maybe it’s the only reasonable way to implement it, but I think these design decisions combined with the lack of progressive disclosure is why this feature is often criticized and perceived the way it is. You want the compiler to help find the data races, and the data by itself can’t cause a data race – it’s how it’s being used down to individual properties, which is why Sendable also appears to be too blunt of an instrument.

There’s also been a notion that the new warnings are easy to fix. I’m sure some of them are, but that wasn’t the case in my experience. In my frameworks and apps, I had to carefully think about almost every individual instance and then often update tests, etc, which was extremely time-consuming even in smaller well-maintained codebases. Migration seems easier once you’ve done it, but at this point, it’s too late. I wouldn’t underplay how complex it is, especially anything related to closures and delegates.

It also depends on what kind of migration we are talking about. Unless you simply want to get your existing code to compile under Swift 6 by using @unchecked Sendable and unsafe(nonisolated) to essentially ignore most of the Data Race Safety system, you are looking at a rewrite of your concurrency code and the code that depends on it.

Aside

This is pure speculation, but knowing how corporate politics work, I think one of the issues with Swift is that some group within Apple thinks of Swift as a product in itself and not as a means to an end like how Objective-C has always been treated. It leads to time constraints and impossible expectations being set for the teams.

With ten years in, there are some legitimate questions whether the recent changes have resulted in the productivity gains, which is ultimately the only thing that matters. Many new features have been syntax sugar, including property wrappers, result builders, multiple trailing closures, if expressions, and more. Swift now has levels of syntax sugar often surpassing scripting languages. I don’t necessarily say that it’s a bad thing, and as a counterexample, Async/Await, the new ownership model that follows the progressive disclosure principles, improvements to generics and incremental compilation, have all been welcome.

Speaking about compile time, one of Swift’s original premises was that it was “fast,” and you would expect it to apply to the compile time. However, with the current slow compilation, developers have to go to extreme lengths to work this around, including reinventing header files by creating protocol-only modules, which Swift was designed to eliminate. If there was a way to disable some of the language features to improve compile time, I would do it in an instant. I’m bringing this up because I wonder what the impact of data race safety is going to be, especially once it gets upgraded with more advanced techniques for eliminating false positives.

Final Thoughts

I hope Apple returns to Swift’s original tenets and makes it fast and simple, focusing on productivity gains over everything else, and reduce the amount of work the developers need to do, not increase it.

SwiftPM and Xcode

Tue, 09 Jul 2024 14:00:00 +0000

I recently had the pleasure of migrating a relatively large project from CocoaPods to SwiftPM, and I would like to share my experience and some thoughts about how it could be improved.

Adding Dependencies

The existing process for adding dependencies to Xcode target involves multiple steps and is especially convoluted when you have multiple targets, like app extensions. I wanted to make sure that the experience of managing the dependencies is at least as good as in CocoaPods, so I borrowed a page from their playbook. I’m also working with a situation where most of the code is in Xcode targets and can’t be easily extracted to Swift packages.

I created a Modules/Package.swift file and defined a list of products that match my Xcode targets:

let package = Package(
    name: "App",
    products: XcodeSupport.products + [
        .library(name: "MyInternalLibrary", targets: ["MyInternalLibrary"]),
    ],
    // ...
)

enum XcodeSupport {
    static let products: [Product] = [
        .library(name: "XcodeTarget_App", targets: ["XcodeTarget_App"]),
        .library(name: "XcodeTarget_AppTests", targets: ["XcodeTarget_AppTests"]),
        .library(name: "XcodeTarget_ShareExtensions", targets: ["XcodeTarget_ShareExtensions"]),
        // ...
    ]
}

These products are neatly placed at the bottom of the Package.swift and have no source files except for the dummy files stored in Modules/Sources/XcodeSupport/. The libraries produced by these products is what’s get added to “Frameworks, Libraries, and Embedded Content” in Xcode.

The “actual” dependencies are specified in the same Modules/Package.swift file:

enum XcodeSupport {
    static let targets: [Target] = [
        .target(name: "XcodeTarget_App", dependencies: [
            .product(name: "Pulse", package: "Pulse"),
            .product(name: "PulseUI", package: "Pulse"),
            .product(name: "Nuke", package: "Nuke"),
            .product(name: "NukeUI", package: "Nuke"),
            // ...
        ])
        // ...
    ]
}

Now if you need to add a new dependency, you simply add it in Modules/Package.swift, and you are done. You never need to mess with the .pbpxroj file.

The dependencies, including the transitive ones, are pinned in the ./MyApp.xcworkspace/xcshareddata/swiftpm/Package.resolved file as usual. I added Modules/Packages.resolved to .gitignore to make sure if someone opens Packages.swift, the Package.resolved file never gets committed into the repo.

Better Developer Experience

With a few extra steps, I achieved my goals, and I think it was an acceptable solution for SwiftPM’s early days. But it leaves a lot to be desired. The ideal developer experience for me would’ve looked the following way:

You invoke the “Add Package Dependency” action and it shows the existing dialog.

When you select a package, Xcode either creates a new Package.swift file in the root project directory or adds a dependency to the existing file:

let package = Package(
    name: "App",
    dependencies: [
        // ...
        .package(url: "https://github.com/kean/Nuke", from: "12.0.0")
    ],
    // ...
)

The pinned dependencies should be saved in Package.resolved file stored side by side with the Package.swift file so that if you open a package, it uses the same pins as the Xcode project, and there is no confusion where the dependencies are pinned.

To add a dependency to an Xcode target you have two options:

Add it to “Frameworks, Libraries, and Embedded Content” manually
Add it in code using targets automatically generated by Xcode and/or SwiftPM:

let project = Project(
    // ...
    targets: [
        .target(name: "App", dependencies: [
            "MyInternalLibrary",
             .product(name: "Nuke", package: "Nuke"),
        ])
    ]
)

Yes, borrowing a bit from Tuist.

To delete a dependency, you would Option-Click on the dependency in the Package.swift file and select “Delete Dependency”, which would remove it from the list of dependencies and also from all the targets.

Technical Limitations

Of course, the Package.swift file is a Swift file, so if it is complicated enough, some of these things won’t work. But I think it’s an acceptable and understandable trade-off because it’s just a bit of a convenience on top of a human-readable source file. If you are unhappy with a diff it creates, you’ll change it. Currently, these features don’t exist at all, even for simple package files.

Other Issues

In addition to the issues with the developer experience, which I can live with, there are a couple of major issues with no straightforward solutions that really sour the experience of using SwiftPM, especially coming from other package managers and platforms.

Bundle Duplication. Xcode is smart enough to link the dependencies used by more than one target dynamically, but, unfortunately, their bundles still end up being duplicated in all of the targets that depend on them.
Invalid Bundle.module. If you include a SwiftPM package that has resources in one of your Xcode test targets, the library is not be able to locate its resources. I had to stop using Bundle.module and switched to an updated version that first looks for bundles in ProcessInfo.processInfo.environment["XCTestBundlePath"].
Resolve Packages. Xcode constantly restarts package resolution, even as you type in your Package.swift file, which is especially problematic during rebasing or any other Git operations. I’m usually reserved with my comments, but I can’t overstate how horrible the experience is. It’s a good trade-off only if you are one person working on a small project in a single branch. There has to be a way to turn it off and a simple command like swiftpm install to resolve the dependencies.

Final Thoughts

Despite the existing issues, I feel more confident using SwiftPM for medium- to large-size projects, but I hope to see the improvements that will make it a no-brainer decision to switch to it for projects of any size.

Search

Tue, 24 Jan 2023 14:00:00 +0000

Starting with iOS 15, SwiftUI supports search thanks to the new .searchable modifier. It was also extended with the support for tokens in iOS 16 which was exactly what I was waiting for. For me, it was a perfect opportunity to rethink search in Pulse.

Pulse is now infinitely more useful thanks to two new major features in version 3.2: a powerful search with filters and scopes, and a redesigned console that now supports sorting and grouping of messages.

To start using the new search, simply press “Tab” to focus on a search field, and start typing. It will automatically suggest relevant filters, auto-complete certain entries like domains, and search in multiple scopes like response headers and bodies.

Search is just one of the features introduced in version 3.2. So let me show you the rest. This is super exciting because this release is packed with features.

I will cover some of the .searchable basics in the article, but if you just want to learn the API and are not interested in Pulse, go through the Apple’s “Adding search to your app” article instead. It’s one of the best new articles – love it.

Searchable

When you open search for the first time, it shows you a list of available filters and search scopes. And if you’ve used one before, it’ll be on the top of the suggestions list with a prefilled value. Hit “Tab”, and it’ll add the suggestion filter. Or hit “Return”, and it’ll use the input as a plain search term (or wildcard, or regex).

To add a search bar, I use the new API introduced in iOS 16 that supports tokens and fallback to the previous API on the earlier versions:

struct ConsoleView: View {
    var body: some View {
        ConsoleListView()
            .searchable(text: $viewModel.text, tokens: $viewModel.tokens, token: {
                Label($0.title, systemImage: image)
            })
            .onSubmit(of: .search, viewModel.onSubmit)
    }
}

struct ConsoleListView: View {
    @Environment(\.isSearching) private var isSearching

    var body {
        List {
            if isSearching {
                ConsoleSearchableListContent(viewModel: viewModel)
            } else {
                ConsoleRegularListContent(viewModel: viewModel)
            }
        }.listStyle(.grouped)
    }
}

There is a way to track when the search is enabled with the isSearching environment variable, but there is one gotcha: it has to be added in a subview of the view where you add .searchable. It’s readonly which is a shame.

When you select the “tokens”, they are displayed directly in the search bar, and you can easily remove them. It’s a nice feature because it saves a lot of vertical space and is consistent with many other apps on iOS, e.g. Mail.

SwiftUI also provides a default UI for displaying suggested search tokens (suggestedTokens), but it’s a bit limited and covers the entire screen.

Suggestions

Pulse is smart about the suggested filters. Just to give you a few examples:

Start typing 2 and it recognizes it’s likely the beginning of a status code and suggests: Status Code: 2XX. You can also specify status code ranges: 200-300, 200..<300 – it recognized multiple formats. You can also specify a list instead: 200 203 204. Or make it comma-separated – whatever works for you.
Start typing a host from one of the requests, and it autocompletes it.
Start with /path, and it recognizes you want to search by it.

How does this stuff work? I used parser combinators from my other project – Regex. You can learn more about them in one of the older articles. It is by far my favorite programming technique. I slightly modified the parser for Pulse by adding fuzzy matching and non-strict grammar.

Scopes

Pulse searches in multiple scopes in parallel: request and response headers, bodies, and URLs. You can also select what scopes to use if you don’t need all. You can see all the matches in the results list, and when you select one, it opens the response viewer, highlights the matches, and scrolls to the selected one.

This new search streamlines many user scenarios. For example, let’s say you need to find a userId value from the /login response. Previously, you had to know the name of the path and search for it: /login, then open the response body, search again for userId, and only then do you see it. Now you just search for userId, click it, and you are done.

List

List is known for its performance issues. Unfortunately, it was a deal-breaker for Pulse where I need to display hundreds if not thousands of messages and do it in the reverse order with the newest ones constantly getting inserted at the top. So I switched to UITableView and NSTableView, but kept using List on watchOS and tvOS.

Previously, I only needed to display two types of cells, but now, I needed to introduce filters, scopes, new section headers, and, of course, cells for the search results. I didn’t want to pile onto the technical debt. So I had an idea. List is slow only when you display tons of cells. So let’s just not. In version 3.2, I limit the number of displayed items to 100¹ and extend the list when the user scrolls close to the bottom – simple.

With these changes, I was finally able to use List on iOS and macOS, remove a lot of duplicated code, and while at it, I also introduced a slightly refined design for cells that is now consistent across platforms. There is also a new toolbar because I knew switching between regular messages and network requests needed a prime spot. You now also switch to “Logs” and see only plain messages without requests, which is new.

I’m happy with this approach, but I wish there was a native solution. I’m suspecting, there is no need to diff all the elements to animate the changes on the screen. Or, at least, please, please, give us the option to disable the diffing.

Sort By and Group By

When reviewing logs, you often want to find answers to certain questions. For example, what are the requests that took the longest? What transferred the most data? Which ones returned HTML instead of the expected JSON? With version 3.2, you can now easily find answers to these and many other questions thanks to the new “Sort By” and “Group By” features available directly from the toolbar.

The grouping I’m particularly excited about is “Group by Session”. It’ll show you a list of all your app’s sessions, so now it’s super easy to find logs from one of the earlier sessions. The groups are also infinitely nestable: you can create a group, open it and create a group from the selected logs, and so on.

Pins

And last but not least, Pulse now has a proper replacement for the Pins tab that was removed in version 3.0. It took me a while to finally realize the obvious: it’s in the name – just literally pin them to the top.

Final Thoughts

I love building things, especially when I have full control over all aspects of the process. With Pulse, with a limited time, I try to work in quick bursts where I try to make a few good decisions to move it forwards and focus on them. I usually follow the make it work → make it right → make it fast mantra, and with SwiftUI, prototypes are often indistinguishable from the implementation, which is a massive time-saver.

The new search and other list features make Pulse infinitely more useful. They are available today on iOS and are coming soon to other platforms. I hope you give it a try!

This new approach with List is actually kind of perfect for one more reason. The diffing introduces a problem that is a bit more subtle. While List doesn’t display all cells upfront, it needs to know the identifiers of all the displayed entities upfront. That’s a problem if you are using fetchBatchSize to reduce the number of database calls. But if you only display a slice of entities, and if the size of the slice matches your fetchBatchSize, it works as expected: there is only one SELECT * FROM when you open the page: see my Core Data logs before and after. ↩

Pulse 3

Tue, 10 Jan 2023 14:00:00 +0000

Today is my 10th anniversary of programming for Apple platforms, and what better way to celebrate it than with a new major release – Pulse 3.0 is out!

I loved every year I worked on iOS. I started in 2012 with Objective-C and now, thanks to Swift and SwiftUI, I’m able to target all Apple platforms, which is incredible. Pulse 3 is a complete overhaul. It enhances the experience and achieves nearly complete feature parity between iOS, macOS, watchOS, and tvOS with the same codebase.

Pulse is a network logger built with SwiftUI. It integrates on the URLSession level allowing it to see unencrypted traffic and record task metrics available only on this level.

iOS

The original version of Pulse was designed quickly and targeted only iOS, so many of the decisions were incompatible with other platforms. Fortunately, for nearly every issue, there was a better solution that also enhanced the experience on iOS while simplifying the code.

Inspector

The most dramatic changes are probably in the network inspector. The previous version had a convoluted navigation with a segmented control in the navigation bar that was hard to reach and didn’t scale for adding more features. More importantly, it was incompatible with other platforms. This design was there from 0.1 and it was time to improve it.

The simplest solution is often also the best. The inspector now uses a simple List with navigation links. The new version is clearer and surfaces important information. The primary navigation areas such as response and headers viewer are now much easier to reach because they are closer to the bottom of the screen.

The new navigation freed a lot of vertical space. The difference between the old inspector and the new one is stark. Before, the response viewer had an ad-hoc “show fullscreen” button. Not needed anymore. When you click “Response”, you are effectively already fullscreen now.

The response viewer itself is pretty cool because, unlike regular HTTP proxies, it can display decoding errors. And it’s even better now because the theme of “more vertical space” extends to it as well. I adopted searchable API so that the search bar now disappears when it’s not needed. And I also redesigned the toolbar for jumping between search results. It is now displayed in the bottom-right corner, freeing even more vertical space.

The metrics screen is also redesigned. It now clearly shows all individual transactions along with their fetch types and other details. It’s now much easier to understand the lifetime of a request.

In the following example, you immediately see that the task had three transactions: the first request was redirected with 301 (Moved Permanently), followed by a cache lookup with another request to validate it that returned 304 (Not Modified).

Text

Text is often the best interface, and it’s everywhere in Pulse. Where previously you had non-selectable labels, it now uses fully featured text views with text selection, search, and sharing. There are also two new sharing options: HTML and PDF. I’m sure a lot of people will be particularly excited about PDF, especially if you print out code at work. To power these features, I had to rework how I create strings because the previous approach of writings different “renderers” for different outputs didn’t scale well.

In the new system I render things – messages, tasks, response bodies – into attributed strings. The strings are then converted into the requested output format: NSAttributedString -> HTML, NSAttributedString -> PDF, NSAttributedString -> Plain Text. It’s much simpler and produces consistent results. SwiftUI previews were a massive help to iterate on it.

The main navigation also changed in Pusle 3. The MainView from the previous version had a tab bar, which is a good choice for most iOS apps, but not for a tool that you are integrate into an existing app. Most large apps already have their own debug menus and they want to integrate Pulse there.

In Pulse 3, the navigation is now centered around a single screen: ConsoleView that you can either push or present. The Network and the Pins screens became simple filters. And Insights and Settings are now accessible from the new context menu. It also provides quick access for common actions, such as removing logs.

View as Text is yet another new text-based feature. It renders the entire console output as text. But it’s not static text: you can still apply filters, search, expand and collapse network requests, and more. And just like the response viewer, it displays decoding errors inline (see “id” highlighted in red).

Storage

The storage improvements were the primary focus of Pulse 2: massive space savings, improved document format for sharing, and fully SQL-compatible storage – these are just some of the changes it introduced. With this solid foundation, I was able to focus on PulseUI in this release, but there are some improvements to the core framework as well. For example, NetworkLogger now has convenience APIs for filtering out sensitive data or just something you don’t want to be logged for other reasons.

let logger = NetworkLogger {
    // Includes only requests with the given domain.
    $0.includedHosts = ["*.example.com"]

    // Exclude some subdomains.
    $0.excludedHosts = ["logging.example.com"]

    // Exclude specific URLs.
    $0.excludedURLs = ["*/log/event"]

    // Replaces values for the given HTTP headers with "<private>"
    $0.sensitiveHeaders = ["Authorization", "Access-Token"]

    // Redacts sensitive query items.
    $0.sensitiveQueryItems = ["password"]

    // Replaces values for the given response and request JSON fields with "<private>"
    $0.sensitiveDataFields = ["password"]
}

Both include and exclude patterns support basic wildcards (*), but you can also turns them into regex patterns using isRegexEnabled.

tvOS

Now let’s talk about the big screen – Apple TV. The original iOS-centered design was largely incompatible with other platforms. But with the new simplified navigation, I was able to use the network inspector and console with almost no changes on tvOS (and other platforms, but more on that later). I was stunned when I ran the new SwiftUI codebase on these other targets – it just worked. I needed to make only small adjustments. Well, of course, I’m also using native design, so many things come for free.

The main thing I did end up tweaking on tvOS is navigation to take advantage of the big screen. I combined two navigation stacks on a single screen, both in the console and in the network inspector. This way you can access common features, such as filters without ever leaving the console. It also enforces acceptable width for lists so that the existing cells from iOS work well in this context.

watchOS

The watchOS version got a complete overhaul as well and now has nearly complete feature parity with iOS. If you enjoy hiking with your Apple Watch Ultra and have a watchOS app to test – great. You can record and preview logs directly on the device. And when you are ready, you can easily share and view them on a bigger screen.

You can also connect to any device running Pulse remotely with Pulse Pro and view logs in real-time on your Mac.

I got a lot of features “for free” after reworking the iOS version. For example, console and network filters that were initially developed for Pulse Pro now work on all platforms (and with nearly zero conditional code). But there are also some new SwiftUI APIs I integrated on watchOS: AttributedString, searchable, charts, ShareLink, monospace digits for Text, destructive buttons, buttonBorderShape, and more.

macOS

The macOS version is back to its OG triple-column design from App Kit is Done, but now with the new NavigationSplitView APIs and 90% of the code shared with others platforms.

The macOS version has probably changed the most over the last couple of years.

The first version from Pulse 0.x was almost embarrassingly bad, but I’ll add it as a reference point – it’s nice to see the progress. For 1.0, I added proper macOS support with windows, toolbars, and triple-column navigation. The next major advancement was a mostly AppKit standalone Pulse Pro app for viewing logs remotely shared from other devices. With the release of Pulse Pro, I cut the macOS version of the PulseUI console entirely. But with the recent SwiftUI refinements, I started to bring PulseUI back to the Mac. In Pulse 2, I reworked some of the Pulse Pro screens in SwiftUI and put it all together in a simple view.

Pulse 3 is a natural step in the SwiftUIfication of the macOS codebase. I’m sure this isn’t its final form yet, so I don’t want to focus on it as much right now. My next step is to fully rewrite Pulse Pro in SwiftUI – stay tuned for that!

Closing Thoughts

I think I finally figured out SwiftUI – writing it stared to feel as natural as writing UIKit. I use it for everything: design, prototyping, and development. There are fewer and fewer places where I have to fallback to UIKit or AppKit.

SwiftUI works well when you target just a single platform, but you are making a multiplatform app, it’s a complete game changer, and I hope Pulse is proof of that. There is one condition though – it all comes down to the design. You have to come up with the design solutions that are simple and compatible with other platforms, which is often a good thing because simpler things are easier accessible.

Pulse 3 development was completely insane with 215 changed files with 8,597 additions and 8,044 deletions in just under 2 weeks. For me, it’s now time to chill. I hope you would check out Pulse 3 and you’d love it.

Pulse 2.0

Tue, 16 Aug 2022 14:00:00 +0000

Pulse is a logging system for Apple platforms. Pulse 2.0 is almost a complete rewrite that focuses on adding plenty of new major features and optimizing performance.

PulseUI

The first feature developed for 2.0 was pending requests – the console will now show pending tasks with their progress. It uses the new urlSession(_:didCreateTask:) method (iOS 16) to track the created tasks¹. The remote logger also supports this feature. And in addition to basic data tasks, Pulse now supports downloads and uploads.

Improved Metrics

The network inspector now also does a much better job of accurately displaying the information about the requests and their metrics. You can now see both the original and the current request. And it also displays individual transactions.

In the example below, the response is stored in the disk cache but is expired and needs to be validated with the server. You can now clearly see what happens from the transaction list. The first one loads the response from the cache. And the second transaction validates it with the server that returns 304 (Not Modified). That’s why you see “Source: Cache” – a new field on the summary page.

And there are more new fields and sections on the summary page. For example, it now shows a type of recorded task: URLSessionDataTask, URLSessionDownloadTask, etc. There are separate host and path fields in the request section making it easier to see and copy them. And if the URL contains query items, there are also displayed in pairs.

Insights

In addition to tracking individual metrics, Pulse now also analyzes your traffic and presents some key insights in a visual way.

It’ll show you information like the duration of requests, total transfer size, domains, and recent errors and warnings. For example, it’ll surface the requests with redirects and show how much time the app lost on them.

The graphs on this screen are powered by Swift Charts (iOS 16). This API is not yet released and there will be more charts added to this screen when Xcode 14 goes into production this fall.

Decoding Errors

Unlike regular network proxies, Pulse works directly with URLSession. It makes it easier to integrate and see encrypted traffic. It also gives you more information about the requests that any proxy could get.

When you think about network requests from the perspective of an app, you can’t consider a request with failed decoding success. Yet a regular proxy will report 200 OK. There is a new configuration option in NetworkLogger to address that called isWaitingForDecoding. When enabled, it gives the app control over when to complete the request. If the app reports a decoding error, Pulse will now display it directly in the response body, highlighting the field that produced the error.

File viewer now supports more content types: PDF, Query Items, and HTML. There is now basic highlighting for HTML and an option to open it in a browser for preview. The file viewer is now also the default screen you see when you tap on a request, and you can also open it fullscreen.

There are a ton of other minor fixes, tweaks and features across the app and there is no space to cover them. Many of them are thanks to the new APIs added to SwiftUI this year. For example, custom previews for context menus.

Back to the Mac

Pulse has a history on a Mac. The initial version looked and worked more like it was designed for an iPad despite being a native macOS app. Then came Pulse Pro designed as a professional macOS app with a primary goal of working as a target for remote logging. But something was lost in that transition.

Pulse Pro is a standalone app and not part of the PulseUI framework, and there was no longer any way to bundle PulseUI into a macOS app that people asked for. With version 2.0, PulseUI has a purpose-built macOS view designed to work well when integrated into the existing app. Pulse now also supports remote logging on a Mac, which is easy to enable using the Settings screen.

Any Platform

In addition to iOS and macOS, Pulse is, as usual, also available on watchOS and tvOS. Both versions were updated to support most of the latest features (at practically no extra cost). For example, it also supports pending requests:

If you are working on a tvOS app, you can also find Pulse useful. It provides the same features as a watchOS app: you can view logs directly on the device and it supports remote logging.

Documentation

The documentation for Pulse is rewritten from scratch and generated using DocC. With the addition of Pulse, all my frameworks now use DocC. It’s used not just for generating API references, but for articles as well. And most of the types have “extensions” as well as refining the documentation.

Performance

The new features are exciting, but there are also some significant performance improvements under the hood I would like to mention.

Space Savings

LoggerStore now uses up to 90% less space. The main improvement comes from a simple yet effective change: compression. The request and response blobs are now compressed using Apple’s lzfse. I found it to be about x3 times faster than zlib and with often better compression ratio. The same compression is also used for remote logging.

The small blobs (<16 KB) are now efficiently stored directly in SQLite. The limit might seem small, but it applies after compression. If you take an example repos.json file with 3020 lines, it compresses from 161 KB to just over 11 KB which fits the inline limit.

When performing optimizations, it’s crucial to measure. Make sure your test data well represents the real data. If you are working with Core Data or SQLite, you can use DB Browser for SQLite to analyze the data. You can also use sqlite3_analyzer to see exactly how much space each table and index takes.

There a bunch of other small improvements under the hood. For example, I switched from SHA256 to SHA1 for generating keys for blob deduplication. SHA1 is 30% faster and uses just 40 characters instead of 64 for file names.

The new store also no longer stores any unstructured data – everything is stored in the database, including task metrics, and can be queried with SQL. You can track exactly how much space Pulse is taking on the new Store Details screen.

Optimized for Images

The logger now stores compressed thumbnails instead of full-resolution images. It uses HEIF for efficient storage, and the deduplication used for other blobs also applies. The savings are dramatic. For the image I used in the demo, I saved 99.9% of space.

Thanks to these improvements, it became feasible to use Pulse with Nuke, so starting with Nuke 11.1, there is now a simple way to integrate the frameworks.

Document Format

Pulse allows you to share logs and open them on another machine. For that reason, it has a custom document format (.pulse). When I created the original format for v1.0, I decided to use ZIP archives as its base because of its compression and the ability to decompress contents (blobs) on-demand. I used an excellent ZIPFoundation framework for this purpose. But after increasing the minimum deployment target in Pulse 2.0, I was finally able to use lzfse and decided to re-evaluate this decision.

In Pulse 2.0, the blobs are compressed not just before sharing, but also at rest, significantly reducing the store size. It also means they no longer need to be compressed before sharing, making it much faster. And with native lzfse taking care of compression, I was able to remove ZIPFoundation reducing the framework size. I switched to SQLite, a perfect choice for creating custom document formats.

These are not the only improvements to sharing. The new Sharing Options screen allows you to limit how much data you want to share. By default, it only sends the logs from the current session, often dramatically reducing the shared file size.

Integrations

In addition to support for Nuke, Pulse is easy to integrate with any URLSession-based API clients, such as Get. You can integrate it with Pulse 2.0 in under 20 seconds to view your network traffic in-app.

Final Thoughts

I can’t close this without talking a bit about SwiftUI, which 90%+ of Pulse is built with. I developed it in Xcode 14 (betas 3-5), and I was pleasantly surprised with the Canvas improvements. I think we are now at the inflection point where the pros of using SwiftUI outweigh the cons, assuming you can target only the latest OS versions. The issue isn’t even the lack of the new APIs on the earlier versions, but the differences in the behavior of the existing ones.

Both Pulse and Pulse Pro are open-source and free, as usual. And if you decide to use it in your app, please support it on GitHub.

If you want pending tasks to work on the previous versions of the OS, you can track the same events manually using NetworkLogger/logTaskCreated(_:) API. ↩

Introducing CreateAPI

Tue, 04 Jan 2022 14:00:00 +0000

If you’ve tried OpenAPI spec generators, you know how it goes. They get you about 60-80% there, but you end up having to modify the code by hand. For one of the specs that I tested – GitHub REST API spec – a popular code generator produces more than 300 compile-time errors, which is not ideal. With CreateAPI, I pushed well beyond just making sure the generated code compiles.

It’s Fast: processes specs with 100K lines of YAML in less than a second
Reliable: tested on 1KK lines of publicly available OpenAPI specs producing correct code every time
Smart: generates Swift code that looks like it’s carefully written by hand
Customizable: offers a ton of customization options

I started with a powerful foundation: OpenAPIKit by Mathew Polzin. It takes care of the parsing and validation, so CreateAPI can focus purely on code generation.

Snapshot Testing

I went to the extreme when testing CreateAPI. I wrote a simple snapshot testing utility that takes a couple of hundred publicly available OpenAPI specs from APIs Guru and other sources and feeds them to CreateAPI. It then makes sure that the generated code doesn’t miss any schemas, paths, or properties from the input specs, and that all of the generated code compiles successfully.

One of the main examples I used was GitHub REST API spec. It’s a massive spec with more than 70K lines of YAML. For this spec, I went further than just making sure it compiles. I went through all (or almost all) paths and entities making sure they match the documentation. I also wrote unit tests that take mock JSONs provided by GitHub and make sure the Codable models handle them correctly at runtime. I’m planning to release the generated code as a separate framework – OctoKit.

Optimizations

I just have to talk about performance. CreateAPI is optimized to run on multicore processors like M1 Pro/Max. There is parallelization at every stage; even parsing is partially parallelized. And code generation saturates all available cores. As a result, it processes 100K lines of OpenAPI specs in less than a second.

CreateAPI was built entirely on a 10-Core M1 Pro, which made it feasible to work with these massive test inputs: 1KK of OpenAPI specs and 500K of generated Swift code. This beast compiles 500K lines of Swift code (heavily modularized) in less than 2 minutes – absolutely insane.

Code Generation

And finally, let’s talk about some of the optimizations CreateAPI does to the produced code. Here are just a few examples:

Swifty Booleans

Uses of Boolean methods and properties should read as assertions about the receiver when the use is nonmutating, e.g. x.isEmpty

From https://www.swift.org/documentation/api-design-guidelines/

Unfortunately, it’s uncommon for web APIs to follow this convention. This is why CreateAPI automatically generates Swifty property names for you.

visible:
  type: boolean

Becomes:

public var isVisible: Bool

It’s also smart enough not to add is when it’s not needed:

has_issues:
  type: boolean

public var hasIssues: Bool

For every “smart” feature, CreateAPI has an option to either fully disable it, or add exceptions. For example, you can rename anything in the generated coded: properties, types, enums, etc:
rename:
  # Rename properties, example:
  #   - name: firstName
  #   - SimpleUser.name: firstName
  properties: {}

Abbreviations

CreateAPI automatically capitalizes common abbreviations, making them look more “Swifty”.

Before:

public var repoId: String
public var repoUrl: URL

After:

public var repoID: String
public var repoURL: URL

Ordering Properties

Most generators ignore the original order of properties from the specs. Yet they are often designed with a particular order in mind. CreateAPI preserves the order of the properties (thanks to the ordered dictionaries in OpenAPIKit).

CreateAPI also has an option to order properties alphabetically.

Removing Noise

Readability is important. CreateAPI makes sure that the generated code is clean and concise. For example, most generators add all enum case names by default – it’s just simpler to implement it this way:

public enum Status: String, Codable, Equatable, CaseIterable {
    case placed = "placed"
    case approved = "approved"
    case delivered = "delivered"
}

CreateAPI doesn’t add redundant names. It’s a small thing, but all these small things add up:

public enum Status: String, Codable, CaseIterable {
    case placed
    case approved
    case delivered
}

Another example is requests and queries. For simple requests, CreateAPI doesn’t generate a dedicated class or struct to represent a request and generates a compact version instead. It significantly reduces the amount of generated code.

public func post(accessToken: String) -> Request<OctoKit.Reaction>
    .post(path, body: ["accessToken": accessToken])

The same applies to simple URL queries:

private func makeGetQuery(_ perPage: Int, _ cursor: String) -> [(String, String?)] {
    [("per_page", String(perPage)), ("cursor", cursor))]
}

Inlining Typealiases

Authors of OpenAPI specs often define arrays with items defined inline:

search-result-text-matches:
  title: Search Result Text Matches
  type: array
  items:
    type: object
    properties:
      object_url:
        type: string
      object_type:
        nullable: true
        type: string
      ...

Many tools fail to produce anything useful for these specs. Here’s one example:

public typealias SearchResultTextMatches = [SearchResultTextMatches]

It doesn’t compile - the element definition is completely missing and the typealias refers to itself.

In that situation, CreateAPI uses multiple techniques that together produce the following output:

public struct SearchResultTextMatch: Codable {
    public var objectURL: String?
    public var objectType: String?
    public var property: String?
    // ...

    public init(objectURL: String? = nil, objectType: String? = nil, ...) {
        // ...
    }

    private enum CodingKeys: String, CodingKey {
        case objectURL = "object_url"
        case objectType = "object_type"
        case property
        // ...
    }
}

Here is what happens under the hood:

CreateAPI encounters a schema named "search-result-text-matches" of an "array" type.
It checks the type of the element – it’s an anonymous object defined inline.
It generates a struct declaration for the element schema and names it SearchResultTextMatch - a singularized form of "search-result-text-matches".
It skips adding a typealias because it can be inlined later (can be disabled with isInliningTypealiases)

When the "search-result-text-matches" schema is used as a reference anywhere else in the spec, CreateAPI inlines the typealias value:

// Usage
public struct TopicSearchResultItem: Codable {
    public var textMatches: [SearchResultTextMatch]
    // ...

Comments

CreateAPI adds all comments and examples from the spec, but it’s also smart enough not to add redundant comments.

For example, in the following schema, the title matches the description, so it can keep only the title. But the title also matches the name of the entity, so the comments are completely redundant.

validation-error:
  title: Validation Error
  description: Validation Error
  type: object
  required:
    - message
    - documentation_url

public struct ValidationError: Codable {
    public var message: String
    public var documentationURL: String
    // ...

Edge Cases

After going through 1KK lines of OpenAPI specs, I hit a ton of edge cases. I just want to add one example. Here’s what I found in Telegram Bot spec:

emoji:
  default: 🎲
  type: string
  enum:
    - 🎲
    - 🎯
    - 🏀
    - ⚽
    - 🎰

None of the generators I tried were able to handle it correctly. The problem is that a naive approach doesn’t work because you can’t use emojis as enum cases in Swift. CreateAPI uses String Unicode APIs to generate the following case names:

public enum Emoji: String, Codable, CaseIterable {
    case gameDie = "🎲"
    case directHit = "🎯"
    case basketballAndHoop = "🏀"
    case soccerBall = "⚽"
    case slotMachine = "🎰"
}

Pre-Release

I pushed the first pre-release version of CreateAPI, and it joined the rest of the frameworks for working with web APIs:

Nuke - image loading and caching
NukeUI - UI components for image loading
Get - web API client built using async/await
CreateAPI - code generator for OpenAPI specs
Pulse - network logger and inspector
URLQueryEncoder - URL query encoder based on Codable
NaiveDate - working with dates without timezones
HTTPHeaders - simple handling of HTTP response headers

There are still a ton of improvements in the backlog, and I would also appreciate any community contributions!

Web API Client in Swift

Sun, 21 Nov 2021 14:00:00 +0000

Updates

Aug 19, 2022. Updated to Get 2.0

It’s been more than four years since my previous API Client in Swift (archived) post. A lot has changed since then. With the addition of Async/Await and Actors, it’s now easier and more fun than ever to design custom web API clients in Swift. The new version went through a radical redesign and I can’t wait to share more about it.

I’m going to focus on REST APIs and use GitHub API as an example. Before I jump in, here is a quick look at the final result:

// Create a client
let client = APIClient(baseURL: URL(string: "https://api.github.com"))

// Sending requests
let user: User = try await client.send(Request(path: "/user")).value

var request = Request(path: "/user/emails", method: .post)
request.body = ["kean@example.com"]
try await client.send(request)

The code from this article is the basis of kean/Get.

Overview

Every backend has its quirks and usually requires a client optimized for it. This article is a collection of ideas that you can use for writing one that matches your backend perfectly.

The previous version of the client was built using Alamofire and RxSwift. It was a good design at the time, but with the recent Swift changes, I don’t think you need dependencies anymore. I’m going with Apple technologies exclusively: URLSession, Codable, Async/Await, and Actors.

Implementing a Client

Let’s start by defining a type for representing requests. It can be as complicated as you need, but here is a good starting point:

public struct Request<Response> {
    var method: HTTPMethod
    var url: URL?
    var query: [String: String]?
    var body: Encodable?
}

To execute the requests, you use a client¹. It’s a small wrapper on top of URLSession that is easy to modify and extend. You initialize it with a host making it easy to change the environments at runtime.

public actor APIClient {
    private let session: URLSession
    private let baseURL: URL
    // ..
    
    public init(baseURL: URL,
                configuration: URLSessionConfiguration = .default,
                delegate: APIClientDelegate? = nil) {
        self.url = url
        self.session = URLSession(configuration: configuration)
        self.delegate = delegate ?? DefaultAPIClientDelegate()
    }

There are two types of send() methods – one for Decodable types and one for Void that isn’t decodable.

extension APIClient {
    public func send<T: Decodable>(_ request: Request<T>) async throws -> T {
        try await send(request, decode)
    }
    
    public func send(_ request: Request<Void>) async throws -> Void {
        try await send(request, { _ in () })
    }

    private func send<T>(_ request: Request<T>, 
                         _ decode: @escaping (Data) async throws -> T) async throws -> T {
        let urlRequest = try await makeURLRequest(for: request)
        let (data, response) = try await send(urlRequest)
        try validate(response: response, data: data)
        return try await decode(data)
    }

    // The final implementation uses a custom URLSession wrapper compatible with iOS 13.0
    private func send(_ request: URLRequest) async throws -> (Data, URLResponse) {
        try await session.data(for: request, delegate: nil)
    }
}

APIClient takes full advantage of async/await, including the new URLSession async/await APIs. It also performs encoding and decoding on detached tasks, reducing the amount of work done on the APIClient.

let value = try await Task.detached { [decoder] in
    try decoder.decode(T.self, from: data)
}.value

Getting back to Codable, I think we, as a developer community, have finally tackled the challenge of parsing JSON in Swift. So I’m not going to focus on it. If you want to learn more, I wrote a post a couple of years ago with some Codable tips – most are still relevant today.

The rest of the code is relatively straightforward. I’m using URLComponents to create URLs, which is important because it percent-encodes the parts of the URLs that need it.

The client works with JSON, so its sets the respective “Content-Type” and “Accept” HTTP header values automatically.

func makeRequest(url: URL, method: String, body: Encodable?) async throws -> URLRequest {
    var request = URLRequest(url: url)
    request.allHTTPHeaderFields = headers
    request.httpMethod = method
    if let body = body {
        request.httpBody = try await Task.detached { [encoder] in
            try encoder.encode(AnyEncodable(value: body))
        }.value
        if request.value(forHTTPHeaderField: "Content-Type") == nil {
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        }
    }
    if request.value(forHTTPHeaderField: "Accept") == nil {
        request.setValue("application/json", forHTTPHeaderField: "Accept")
    }
    return request
}

Being able to use async functions right inside the makeRequest() method without all the boilerplate of using closures is just pure joy.

The only remaining bit is a validate() method where I check that the response status code is acceptable. It also gives a delegate a chance to decide what error to throw. Most APIs will have a standard JSON format for errors – this is a good place to parse it.

func validate(response: URLResponse, data: Data) throws {
    guard let httpResponse = response as? HTTPURLResponse else { return }
    if !(200..<300).contains(httpResponse.statusCode) {
        throw APIError.unacceptableStatusCode(httpResponse.statusCode)
    }
}

And that’s it, a baseline APIClient. It already covers most of the needs of most users and there many ways to extend it.

Extending the Client

Getting the basics right is usually easy, but what about more advanced use-cases?

User Authorization

Every authorization system has its quirks. If you use OAuth 2.0 or a similar protocol, you need to send an access token with every request. One of the common ways is by setting an “Authorization” header.

One of the advantages of Alamofire is the infrastructure for adapting and retrying requests which is often used for authorization. Reimplementing it with callbacks is no fun, but with async/await, it’s a piece of cake.

The first piece is the client(_:willSendRequest:) delegate method that you can use to “sign” the requests.

final class YourAPIClientDelegate: APIClientDelegate {
    func client(_ client: APIClient, willSendRequest request: inout URLRequest) {
        request.setValue("Bearer: \(accessToken)", forHTTPHeaderField: "Authorization")
    }
}

If you look at setValue(_:forHTTPHeaderField:) documentation, you’ll see a list of Reserved HTTP Headers that you shouldn’t set manually. “Authorization” is one of them… URLSession supports seemingly every authorization mechanism except the most popular one. Setting an “Authorization” header manually is still the least worst option.

The client(_:willSendRequest:) method is also a good way to provide default headers, like “User-Agent”. But you can also provide fields that don’t change using httpAdditionalHeaders property of URLSessionConfiguration.

If your access tokens are short-lived, it is important to implement a proper refresh flow. Again, easy with async/await.

private func performRequest<T>(attempts: Int = 1, send: () async throws -> T) async throws -> T {
    do {
        return try await send()
    } catch {
        guard try await delegate.client(self, shouldRetry: task, error: error, attempts: attempts) else {
            throw error
        }
        return try await performRequest(attempts: attempts + 1, send: send)
    }
}

I count four suspension points. Now think how more complicated and error-prone it would’ve been to implement it with callbacks.

Now all you need is to implement a shouldClientRetry(_:withError:) method in your existing delegate and add the token refresh logic.

final class YourAPIClientDelegate: APIClientDelegate {
    func shouldClientRetry(_ client: APIClient, withError error: Error) async -> Bool {
        if case .unacceptableStatusCode(let status) = (error as? YourError), status == 401 {
            return await refreshAccessToken()
        }
        return false
    }
    
    private func refreshAccessToken() async -> Bool {
        // TODO: Refresh access token
    }
}

The client might call shouldClientRetry(_:withError:) multiple times (once for each failed request). Make sure to coalesce the requests to refresh the token and handle the scenario with an expired refresh token.

I didn’t show this code in the original APIClient implementation to not over-complicate things, but the project you find at GitHub already supports it.

If you are thinking about using auto-retries for connectivity issues, consider using waitsForConnectivity instead. If the request does fail with a network issue, it’s usually best to communicate an error to the user. With NWPathMonitor you can still monitor the connection to your server and retry automatically.

Client Authorization

On top of authorizing the user, most services will also have a way of authorizing the client. If it’s an API key, you can set it using the same way as an “Authorization” header. You may also want to obfuscate it, but remember that client secrecy is impossible.

Another less common but more interesting approach is mTLS (mutual TLS) where it’s not just the server sending a certificate – the client does too. One of the advantages of using certificates is that the secret (private key) never leaves the device.

URLSession supports mTLS natively and it’s easy to implement, even when using the new async/await API (thanks, Apple!).

final class YourTaskDelegate: URLSessionTaskDelegate {
    func urlSession(_ session: URLSession, didReceive challenge: URLAuthenticationChallenge)
        async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
        let protectionSpace = challenge.protectionSpace
        if protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust {
            // You'll probably need to create it somewhere else.
            let credential = URLCredential(identity: ..., certificates: ..., persistence: ...)
            return (.useCredential, credential)
        } else {
            return (.performDefaultHandling, nil)
        }
    }
}

The main challenge with mTLS is getting the private key to the client. You can embed an obfuscated .p12 file in the app, making it hard to discover, but it’s still not impenetrable.

SSL Pinning

The task delegate method for handling the server challenges is also a good place for implementing SSL pinning.

There are multiple ways how to approach this, especially when it comes to what to pin. If you pin leaf certificates, you sign up for constant maintenance because certificates need to be rotated. The simplest option seems to be pinning CA certificates or public keys. Starting with iOS 14, it can be done very easily by adding the keys to the app’s plist file.

HTTP Caching

Caching is a great way to improve application performance and end-user experience. Developers often overlook HTTP cache natively supported by URLSession To enable HTTP caching the server sends special HTTP headers along with the request. Here is an example:

HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
Expires: Mon, 26 Jan 2016 17:45:57 GMT
Last-Modified: Mon, 12 Jan 2016 17:45:57 GMT
ETag: "686897696a7c876b7e"

This response is cacheable and will be fresh for 1 hour. When it becomes stale, the client validates it by making a conditional request using the If-Modified-Since and/or If-None-Match headers. If the response is still fresh the server returns status code 304 Not Modified to instruct the client to use cached data, or it would return 200 OK with a new data otherwise.

By default, URLSession uses URLCache.shared with a small disk and memory capacity. You might not know it, but already be taking advantage of HTTP caching.

HTTP caching is a flexible system where both the server and the client get a say over what gets cached and how. With HTTP, a server can set restrictions on which responses are cacheable, set an expiration age for responses, provide validators (ETag, Last-Modified) to check stale responses, force revalidation on each request, and more.

URLSession (and URLCache) support HTTP caching out of the box. There is a set of requirements for a response to be cached. It’s not just the server that has control. For example, you can use URLRequest.CachePolicy to modify caching behavior from the client. You can easily extend APIClient to support it if needed².

extension APIClient {
    func send<Response>(
        _ request: Request<Response>,
        cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
    ) async throws -> Response where Response: Decodable {
        // Pass the policy to the URLRequest
    }
}

Downloads

By default, the send() method of APIClient uses data(for:delegate:) method from URLSession, but with the existing design, you can easily extend it to support other types of tasks, such as downloads.

extension APIClient {
    public func download(_ request: Request<Void>) async throws -> (URL) {
        let request = try await makeRequest(for: request)
        let (url, response) = try await session.download(for: request, delegate: nil)
        try validate(response: response)
        return url
    }
}

And if the Request type is not working for you, it’s easy to extend too. You can also just as easily add new request types, or even URLRequest directly if you need to. Although for a typical REST API, Request is all you are ever going to need.

Environments

APIClient is initialized with a baseURL, making it easy to switch between the environments in runtime. I typically have a debug menu in the apps with all sorts of debug settings, including an environment picker – it’s fast and easy to build with SwiftUI. I added the code generating this screen in a gist.

Defining an API

For smaller apps, using APIClient directly without creating an API definition can be acceptable. But it’s generally a good idea to define the available APIs somewhere to reduce the clutter in the rest of the code and remove possible duplication.

I’ve tried a few different approaches for defining APIs using APIClient, but couldn’t decide which one was the best. They all have their pros and cons and are often just a matter of personal preference.

REST APIs are designed around resources. One of the ideas I had was to create a separate type to represent each of the resources and expose HTTP methods that are available on them. It works best for APIs that closely follow (REST API design). GitHub API is a great example of a REST API, so that’s why I used it in the examples.

public enum Resources {}

// MARK: - /users/{username}

extension Resources {
    public static func users(_ name: String) -> UsersResource {
        UsersResource(path: "/users/\(name)")
    }
    
    public struct UsersResource {
        public let path: String

        public var get: Request<User> { .init(path: path) }
    }
}

// MARK: - /users/{username}/repos

extension Resources.UsersResource {
    public var repos: ReposResource { ReposResource(path: path + "/repos") }
    
    public struct ReposResource {
        public let path: String

        public var get: Request<[Repo]> { .init(path: path) }
    }
}

Usage:

let repos = try await client.send(Resources.users("kean").repos.get)

This API is visually appealing, but it can be a bit tedious to write and less discoverable than simply listing all available calls. I’m also still a bit cautious about over-using nesting. I used to avoid it in the past, but the recent improvements to the Xcode code completion made working with nested APIs much easier. But again, this is just an example.

There are man suggestions online to model APIs as an enum. This approach might make your code harder to read and modify and lead to merge conflicts. When you add a new call, you should only need to make changes in one place.

Tools

It’s not just Swift that’s getting better. The modern tooling is also fantastic.

OpenAPI

Remember the infamous Working with JSON in Swift post from 2016? Yeah, we are way ahead now. Ask your backend developers to provide OpenAPI spec for their APIs and use code generation to create Codable entities.

Postman and Paw are great ways to explore APIs. You can import an OpenAPI spec and it will generate a Collection for you so that you have all the APIs always at your fingertips. GitHub API that’s I’m using in the examples also recently git its own OpenAPI spec. You can download it and import it into Postman to try it.

Generating Codable entities is also extremely easy. There are a ton of tools available for working with OpenAPI specs. I also created one optimized for Get, named CreateAPI – check it out.

If you don’t have an OpenAPI spec, you can turn a sample JSON into a Codable struct using quicktype.io and tweak it.

Logging

Pulse is a powerful logging system for Apple Platforms.

It requests a single line to setup to work with APIClient. The advantage of doing it at that level is that you don’t need to worry about TLS and SSL pinning, and you collect more information than a typical network proxy does thanks to the direct access to URLSession.

let client = APIClient(baseURL: URL(string: "https://api.github.com")) {
    $0.sessionDelegate = PulseCore.URLSessionProxyDelegate()
}

For a complete guide on using Pulse, see the official documentation.

Mocking

My preferred way of testing ViewModels is by writing integration tests where I mock only the network responses. There are a many mocking tools to chose from. I’m used WeTransfer’s Mocker for unit-testing APIClient itself.

private let host = "api.github.com"

override func setUp() {
    super.setUp()
    
    let configuration = URLSessionConfiguration.default
    configuration.protocolClasses = [MockingURLProtocol.self]

    client = APIClient(host: host, configuration: configuration)
}

func testGet() async throws {
    // Given
    let url = URL(string: "https://\(host)\(Resources.user.get.path)")!
    Mock(url: url, dataType: .json, statusCode: 200, data: [
        .get: json(named: "user")
    ]).register()
    
    // When
    let user = try await client.send(Resources.user.get)
                                        
    // Then
    XCTAssertEqual(user.login, "kean")
}

cURL

cURL doesn’t need an introduction. There is an extension to URLRequest that I borrowed from Alamofire that I love. It creates a cURL command for URLRequest.

Ideally, you should call cURLDescription on task’s currentRequest - it’s has all of the cookies and additional HTTP headers automatically added by the system.

Final Thoughts

Before I started using Async/Await in Swift, I thought it was mostly syntax sugar, but oh how wrong I was. The way Async/Await is integrated into the language is just brilliant. It solves a bunch of common problems in an elegant way and I barely touched the surface in this article. For example, I’m particularly excited about the new threading model that can reduce or eliminate timesharing of threads. In the future async APIs should be defined exclusively using async functions – bye callbacks, bye [weak self].

Actors take full advantage of Async/Await and the new threading model. It’s just as amazing of an addition to the language, and it solves a very common problem. It’s a bit unfortunate that in the case of the API client, I only used them to move work to the background, but there was no mutable state to protect.

If you want to learn more about Async/Await and Structured Concurrency, look no further than this year WWDC session videos. They are all fantastically well made, and, if you want to dive a bit deeper, read the Swift Evolution proposals.

If you just look at the surface level, let’s see how much code I wrote to implement most of the features from this article:

$ cloc Sources/APIClient/.
       2 text files.
       2 unique files.
       0 files ignored.

github.com/AlDanial/cloc v 1.90  T=0.01 s (305.1 files/s, 17795.7 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Swift                            3             26             11            148
-------------------------------------------------------------------------------
SUM:                             3             26             11            148
-------------------------------------------------------------------------------

It is not a direct comparison, but Alamofire version 5.4.4 has 7428 lines. This is bonkers. And to think how far we’ve come in just about 10 years – remember ASIHTTPRequest?

References

Meet async/await in Swift (WWDC21)
Explore structured concurrency in Swift (WWDC21)
Swift concurrency: Update a sample app (WWDC21)
Protect mutable state with Swift actors (WWDC21)
Swift concurrency: Behind the scenes (WWDC21)
RESTful web API design (Azure / Architecture)
URL Loading System (Apple)
Increasing Application Performance with HTTP Cache Headers (Heroku Dev Center)
RFC 7234. HTTP/1.1 Caching (IETF)
OpenAPI Initiative
Introducing GitHub’s OpenAPI Description (GitHub Blog)
Certificate and Public Key Pinning (OWASP)
Authentication with signed requests in Alamofire 5 (SwiftLee)
Secret Management on iOS (NSHipster)
What is mutual TLS (mTLS)? (Cloudflare)
Preventing Man-in-the-Middle Attacks in iOS with SSL Pinning (Ray Wanderlich)
Identity Pinning: How to configure server certificates for your app (Apple)

The client is defined as an actor, but in this case, it doesn’t have to be – in the sample code there is no mutable state to protect. But by making it actor, I make sure the requests are created and started in the background. Based on my performance testing in Nuke, creating requests is a relatively expensive operation and it can be advantageous to move it out of the main thread. In the case of the client, it’s just a matter of changing “class” to “actor” – the rest of the APIs are already async, so there is no change in the APIs needed. But it can be swapped out back to “class”. ↩
The framework’s send() method takes a closure with an inout URLRequest as a parameter allowing the user to modify any of the URLRequest properties. ↩

Best Resources for iOS Engineers

Mon, 15 Nov 2021 14:00:00 +0000

Last week, I made a poll on Twitter asking to share the best learning materials for iOS engineers and was overwhelmed with the number of responses. It was very insightful, and I thought it would be nice to compile the results into a single post, which I did here, adding a few recommendations of my own.

I need your help, Twitter. What are the best learning resources for beginner/intermediate iOS engineers these days (can be paid)?
— Alex Grebenyuk (@a_grebenyuk) November 9, 2021

Most Recommended

There were a couple of outliers that got an absolutely massive number of recommendations.

Standford: CS193p - Developing App for iOS

Beginner, Free

The Stanford University’s course CS193p was by far the most recommended resource. I went through the first few videos myself and was blown away by how packed they are with information.

Stanford hands down. I recommend those lectures to everyone. It's free and it's some of the highest quality content out there: https://t.co/Msv1E7wb2M
— Lauren N. Roth (@lauren_n_roth) November 9, 2021

There are a couple of things to note about this course:

It focuses on SwiftUI. We are still in the transition period where most companies still use UIKit, but it’s already worth investing time into SwiftUI. And you learn much more than just SwiftUI in this course.
The course’s primary target audience is students, and it assumes they are familiar with programming fundamentals. If you are learning programming from scratch, you might want to consider going through other resources first. Having said that, the best way to learn programming is by building things.

100 Days of Swift

Beginner, Free

The second most recommended course is 100 Days of Swift. And it’s not the only resource on Hacking with Swift by Paul Hudson. There is a similar course on SwiftUI – 100 Days of SwiftUI, and there are a ton of other articles and videos.

Unlike Standford’s course, 100 Days of Swift focuses not on app development, but on Swift itself. If you are just starting learning programming, this course is for you.

Highly recommend@twostraws 100 days of swift https://t.co/Ud94Ju0aYg
And @objcio courses https://t.co/DBs9fGdsi1
— inailuy☁️ (@cloudssayhello) November 9, 2021

https://t.co/50rv302VMv and take the 100 days of Swift course. There also a 100 days of SwiftUI course
— Nikolaj Nielsen (@NikolajMosb) November 10, 2021

Udemy - The Complete iOS App Development Bootcamp

Beginner, Paid

It seems uncommon for a paid course to get a lot of recommendations, but this one is an exception and it made the shortlist. I wasn’t able to check it out myself, but if you look at the course’s content, it does look complete. I think right now it might be a better option than Standford’s CS193p if you want to focus on the current technologies, such as UIKit.

Amazing and thorough. This course is hands down one of the best around: https://t.co/y7IG0KD2fk @yu_angela @LondonAppBrewer
— Greg Watkins (@GregWatkins69) November 10, 2021

Ray Wanderlich

Beginner/Indermediate, Free/Paid

This site doesn’t need an introduction. I often find myself using it in my daily work. Ray Wanderlich is the go-to place for finding tutorials on specific topics. But it has more than that. It also has courses, videos, articles, and even books. If there is an iOS topic you are interested in, chances are you’ll find it on this site.

First-Party Resources

I’m surprised nobody linked official Apple documentation in the thread. If I made this poll 6-8 years ago, I’m sure a lot of people would’ve jumped in the thread recommending it. Today, there are a ton of third-party resources that can oftentimes be better than what Apple provides. But despite that, the Apple documentation will always be my primary source of all the information on Apple technologies.

Apple WWDC videos – probably the main source for me. You can often find information not available anywhere else. It’s a bit unfortunate because finding what you are looking for in a video can be time-consuming.
Apple Developer documentation – not quite as good as it used to be, but is still a valuable resource
Apple Tutorials: Develop Apps for iOS – Apple recent venture in the tutorial-creation business. I went through these tutorials and they are well made and informative, but a bit dry.
The Swift Programming Language – reading this book is how I learned Swift. It’s a concise and well-written book and is a must-read. You can learn through it instead using a course.
Swift Evolution – the programming guide doesn’t cover everything and sometimes the best source of information on the newest Swift features can be the Swift Evolution proposals
Human Interface Guidelines (HIG) – design is a major part of iOS development and engineers are often relied on to provide their input. This is a must-read resource for any Apple engineer.
Apple Developer News and Updates – add it to your RSS reader to learn about the latest updates on the platforms. For example, about deadlines to switching to new Xcode vresions or SDKs.
Swift Forums – if you want to keep be up to date with the latest proposals or even participate in discussions

There are so many technologies on Apple platforms that you can’t just go and preemptively learn everything. It’s best when you have a project and you have a need. When you have a need, you have all the motivation you need to study something. Writing an article can also be a good motivator.

Other Recommendations

I received a ton of recommendations in the original poll. Here I’m going to list the ones that didn’t make the shortlist, in no particular order. A word of caution – Apple platforms are constantly evolving, make sure what you are reading is up-to-date.

I’d like to add a couple links myself: iOS Dev Weekly, NSHipster, Use Your Loaf, Cocoa with Love, Little Bites of Cocoa, Krzysztof Zabłocki, Ole Begemann, Increment.

Software Engineering

There is more to software engineering than learning a programming language and a platform you are working on. If you want to get a competitive advantage among other engineers, especially if you don’t have a CS degree, invest time in learning the fundamentals. The good news is that degrees are overrated – you can learn everything they do and more by yourself. It’s not like you need any special equipment or anything.

An incomplete list of everything that you should consider learning (in no particular order):

Git. There are a ton of resources on Git, but I found Pro Git to be the most insightful.
Release and Branching Strategies. I think Trunk-Based Development is hands down the best branching strategy, especially for larger teams.
Algorithms and Data Structures. There are many ways to learn them. I like The Algorithm Design Manual, Steven Skiena and Introduction to Algorithms, Thomas H. Cormen. The former is more approachable.
Terminal and Bash. For me, Swift largely replaced Bash as a scripting language of choice, but I still find myself using Bash often enough. Regardless of your choice, it’s also always worth learning regex.
Concurrency and Reactive Programming. Concurrency is hands down the most challenging aspect of UI development, and there are a ton of things to learn: Swift Structured Concurrency, Combine, parallel programming, synchronization mechanisms, threading. It’s hard, but it comes with practice.
Databases. Learn the basics of relational databases, Core Data, try using SQLite directly, and you are mostly set as far as mobile development goes.
Continuous Integration and Delivery. It’s not just the tools, it’s the practice. You can learn a lot about it by reading Martin Fowler’s articles. If you want to dive deeper, there are a few good books available too. But it’s also tools. On iOS, it largely means learning Fastlane and a CI/CD tool of your choice. You can start by creating a sample project on GitHub and setting up a simple pipeline using GitHub Actions.
Functional Programming. It’s finally mainstream. If you use Swift, you are already using functional programming. But Swift isn’t a pure functional language and it can be a lot of fun learning one. I recommend Structure and Interpretation of Computer Programs (Lisp version) or Haskell (probably the most well-established and well-documented pure functional language out there).
Software Networking. Almost every app uses networking. You generally don’t need to know anything beyond basics HTTP and JSON, but it’s a lot of fun learning how it actually works under the hood. I suggest learning the basics of the networking protocols: TCP/IP, DNS, go through the HTTP specs. Tools like Charles allow you to inspect network traffic. Wireshark can help you learn network protocols. Postman is the best tool to explore and test APIs. OpenAPI is how you document the APIs.
Best Practices. I think “best practices” often do more harm than good, especially taken to the extreme. But they can still be valuable. I would suggest going through Code Complete by Steve McConnel and skipping everything else.
Processes. Atlassian has a pretty good guide on Agile.
Soft Skills. This is probably more important than half of the list. I don’t think there is a shortcut to learning them. You have to practice and always pay close attention to what you are doing. Reading the following books can give you some valuable insights about this side of engineering: The Pragmatic Programmer, The Mythical Man Month, Herding Cats, The Five Dysfunctions of a Team.

This list is far from being complete. There are a variety of specializations in software engineering. You can learn anything if you put your mind to it. I think adding new perspectives is valuable. For example, if you are a mobile engineer, it doesn’t mean that you can’t explore a bit of backend development to expand your perspective (especially now that’s it can be done in Swift).

Interviews

So you learned everything about iOS and software engineering, now you are done, right? Not quite. There is software engineering, and there are software engineering interviews. There is some intersection between the two, but completing coding challenges on an interview is very different from what you typically do at work.

The main difference is speed. Not only do you need to be quick to be able to complete a task within a given timeframe, but you also need to explain your thinking to the interviewer, making it even more complicated. So it’s crucial to set a timer when you are preparing and optimize for speed and practice explaining what you are doing.

Fortunately, there are a ton of tools to help you prepare for interviews. The gold standard is Cracking the Coding Interview, this is hands down the best resource that can help you prepare. I would also recommend leetcode. Another great resource is Tech Interview Handbook. Passing interviews is a special skill and you need to allocate time into learning it unless you want to miss out on some opportunities.

Final Thoughts

Everyone’s path in software engineering is different. It’s highly technical and it requires a ton of time investment. But it can also be extremely rewarding and fun. I hope you’ll find some of the resources from this post useful and they’ll inspire you to learn something new!

If you have any suggestions to the list, feel free to open a PR on GitHub or reach out to me on Twitter. I intend on keeping this post up-to-date.

Pulse Pro

Tue, 05 Oct 2021 14:00:00 +0000

There is always this friction when debugging native apps. You can’t look behind the scenes, unlike browsers with their developer tools. The idea behind Pulse is to bring the same or better debugging experience to native apps.

With the Pulse framework, you can record logs and network requests, view them directly on your device, and share later. And with a new Pulse Pro app for macOS, you can inspect logs remotely in real-time.

The new app is designed to be flexible, expansive, and precise while using all the familiar macOS patterns. It makes it easy to navigate large log files with table and text modes, filters, scroller markers, an all-new network inspector, JSON filters, and more.

Remote Logging

The headlining feature of Pulse Pro is Remote Logging which allows you to view logs and network requests in real-time on your Mac. It’s very easy to use, fast, and reliable. To starting using it, first launch the Pulse Pro app and enable Remote Logging.

When enabled, your Mac becomes discoverable on your local network. You only need to enable it once. Next time you launch Pulse Pro, it will happen automatically.

Then, enable Remote Logging on the device with the Pulse framework installed. When your Mac appears on the list, select it to pair the devices. This extra step is needed to ensure that in a space with multiple devices running Pulse Pro, you’ll have a way to choose which one to connect to. You only need to do the pairing once.

Pulse is written in SwiftUI and is available on all Apple platforms. The same is true with remote logging. It works on iOS, watchOS, tvOS, and macOS if you need to. And it even works in simulators.

As soon as the devices are paired, there is zero additional interaction needed. When the device connects to the Pulse Pro app, the console opens automatically. You can turn this option off later in settings. And the device remembers which Mac it is paired with, so the next time it’s launched, it will connect right away without your interaction.

The logs are stored persistently both on the device with the Pulse framework and by the Pulse Pro app, so you can get back to them later. You can also easily delete them if needed.

Remote Logging is implemented using the new Apple Network framework. It advertises the Bonjour service on the local network and listens to the TCP connections. The client app replicates all the logs to the server using a simple custom binary protocol. It even sends the logs recorded during the app launch while the connection isn’t up yet.

Table Mode

The previous version of the Pulse macOS app was fairly limited. It had an inflexible interface with many iOS-isms. There was only one mode to display information – a list view. You couldn’t toggle between vertical and horizontal layouts. Most of the text in the app was non-selectable. Overall, it just wasn’t taking full advantage of the platform. It was a nice native macOS app, but you couldn’t call it a professional app by any stretch of the imagination.

Mac apps are flexible and adjust to how we individually use them. The first change that I made for Pulse Pro was to replace the list view with a fully adjustable table¹.

When you launch the console for the first time, you are greeted with a simple and clean view with only a few columns and no details panel. You can remove and hide columns, and the app remembers your choice. And, of course, you can sort by a column. The high information density and flexibility allow you to really interact with your data.

Using NSTableView felt surprisingly refreshing. I appreciate how well the delegate-based API design scales with complexity. UIs are inherently hacky, and with delegates (and classes) in AppKit, you can customize every bit of it and also make sure you refresh data efficiently to support big data sets.

When you click to select a row, the details panel is open. You can select between vertical and horizontal layouts, and your choice is saved. If you double-click, the details are opened in a separate window instead.

OK, at this point, you might think these are the table stakes for a macOS app. And you’ll be right. But it was important for me to get these right. I’m primarily an iOS engineer, and I’m breaking new ground here. And bare with me, there is more coming.

Filters

Filters were also fully redesigned. You know how in many apps you configure the filters, but then your only options are to either reset them all or change them back to the defaults manually. In Pulse Pro, you can toggle and reset each filter individually, which is surprisingly convenient. You can collapse the sections you rarely use, and the app saves your preferences. To show filters, hit Cmd+Option+F or click the toolbar item.

Text Mode

Tables are perfect for many use cases, but sometimes nothing beats good old text. But plain text logs have their own problems. As soon as you go plain text, you lose all of the structure. Text usually has no formatting, you can’t open details for the message, and you can’t filter text dynamically like you can a table view. But what if you could?

Toggle the “List” mode, and Pulse Pro will generate the formatted text based on your current filters. Change the filters, and it re-generates the text. I’ve done a ton of optimizations to make it as quick as possible. For example, I cache the strings generated for the individual messages and simply re-compose them later.

The text view itself is also pretty powerful. You can search, filter by line, show line numbers, and change some basic settings like font size. I’m also going the same minimap as in the console soon – more on it later.

You can also toggle “Show Responses” to see nicely formatted network responses inline with your logs. Unlike the traditional plain text logging system, you can make this choice on the display time instead of the time of logging, which is great.

Network Tab

Now let’s talk a bit about networking. The previous app also had a separate “Network” tab, but in reality, it was just the same interface reused interface from the “Console” tab with a filter applied. With Pulse Pro, network tab was completely redesigned. It now has its own view designed from scratch with its own columns and its own filters.

Networks filters were also designed from scratch. The most powerful filter is probably “General” where you can add as many custom filters as you’d like with an easy-to-use interface. You can filter by URL, host, method, request or response body or headers, and more.

Response Viewer

Response viewer has also gotten some love in this release. I added line numbers, the way to change some basic settings, like font size. There is a new color theme that matches Xcode. And, one of the features I’m super excited about, is a jq integration.

jq is a tool for processing JSON, applying the given filter. You can find some examples of what it can do at the jq website. It’s really-really powerful and Pulse Pro makes it super nice to use with side-by-side live results view, and nice output formatting.

Pins

When you scan through the logs, you sometimes find important messages you may want to get back to later. With pins, you can easily do that. Just click on the row number that you’d like to pin, and it will appear in the scroller. You can easily navigate back to this message by simply clicking on the mark in the scroller – just like breakpoints and errors in the Xcode scroller.

In the point release, I’m also adding error marks to the scroller to make it easier to find them. After you use it, you’ll start wondering how you ever read the logs without it.

SwiftUI and AppKit

I wrote the previous version of the app primarily using SwiftUI. You are probably wondering whether that’s the case with Pulse Pro.

The app is a hybrid of SwiftUI and AppKit, but I think it’s fair to say that most of it is still done in SwiftUI. Let’s go through some examples.

The all-new filters panel doesn’t have any AppKit code:

The preferences window and the new status bar menu² I written entirely in SwiftUI. The preferences appear differently in the Canvas than in the app because you can’t use Settings in the previews.

I wrote table views using AppKit. I could probably build them using SwiftUI’s new Table API, but it’s available only in Monterey. By briefly going through it, I’m not sure it supports user-configurable columns, and there are probably more limitations. Fortunately, there is no pressure to write your views using only SwiftUI, and NSTableView is very easy to use.

The text views are also built AppKit (NSTextView and NSAttributedString). But the toolbar at the bottom is built using SwiftUI.

I’m pretty sure I can also replace it with SwiftUI in the future by adopting AttributedString – also Monterey-only. I’m not sure about the line numbers. I used NSRulerView to implement it, so the lack of it in Text might end up being a deal-breaker. But, again, I don’t see any problem with using AppKit for it.

The Metrics view was largely unchanged in Pulse Pro and it’s still written with SwiftUI. The only change I made was to replace the “key-value” views with NSTextView to make the text selectable. In hindsight, I could probably use the new textSelection(_:) API, but too late for that.

And the existing welcome screen is also implemented using only SwiftUI. I updated it a bit for the new version.

And it’s not just the individual screens or components. The entire app navigation is also done using SwiftUI. I’m using NavigationView, WindowGroup, Settings, handlesExternalEvents, Commands to manage windows, toolbars, and command menus. The window management API is fairly limited, so I have to access the underlying windows sometimes. I do that to close windows programmatically, listen to willCloseNotification events, making the existing window a key window, and more.

Even where I didn’t use SwiftUI I still used Xcode Canvas, and it significantly sped up the development. If I told you how quickly I wrote it, you probably won’t believe it. I wish it was a bit more stable though.

Final Thoughts

Pulse is open-source and is available on GitHub as usual. You can integrate it into your app now and view logs using the on-device console. The latest version also includes remote logging, but it requires the Pulse Pro app.

Pulse Pro is available today.

Technically, the previous version of the app was already using NSTableView under the hood for performance reasons, but it was running in a limited mode with no header and only one column. ↩
I created a single menu item with a custom SwiftUI view wrapped into NSHostingView. Initially, there was an issue where it would only receive user events when one of the app’s windows was key. But thanks to this answer, I got it working. ↩

kean.blog

Claude Code Experience

Getting Started

Asking Questions

Writing Code

Starting Small: Refactoring

Feature: Activity Logs and Backups

Prototyping

My Workflow

Where Claude Code Excels

Where It Struggles

Productivity Gains

Final Thoughts

References

Swift 6

Problem

Suggested Solution

Aside

Final Thoughts

SwiftPM and Xcode

Adding Dependencies

Better Developer Experience

Technical Limitations

Other Issues

Final Thoughts

Search

Searchable

Suggestions

Scopes

List

Sort By and Group By

Pins

Final Thoughts

Pulse 3

iOS

Inspector

Text

Navigation

Storage

tvOS

watchOS

macOS

Closing Thoughts

Pulse 2.0

PulseUI

Improved Metrics

Insights

Decoding Errors

Back to the Mac

Any Platform

Documentation

Performance

Space Savings

Optimized for Images

Document Format

Integrations

Final Thoughts

Introducing CreateAPI

Snapshot Testing

Optimizations

Code Generation

Swifty Booleans

Abbreviations

Ordering Properties

Removing Noise

Inlining Typealiases

Comments

Edge Cases

Pre-Release

Web API Client in Swift

Overview

Implementing a Client

Extending the Client

User Authorization

Client Authorization

SSL Pinning

HTTP Caching

Downloads

Environments

Defining an API