whoami
Lucas Jenß
cat /etc/motd
The Coding Journal ツ — Notes taken on an epic coding journey. Technical solutions, debugging notes, and practical guides from the trenches of software development.
ls -la ~/languages/
- drwxr-xr-x
- ▶ PHP
- ▶ Ruby
- ▶ Scala
- ▶ C#
- ▶ JavaScript
- ▶ Objective-C
- ▶ Shell Scripting
ls -la ~/toolchain/
- drwxr-xr-x
- ▶ Typo3
- ▶ Akka
- ▶ Capistrano
- ▶ Git
- ▶ MAMP
- ▶ Adobe Illustrator
- ▶ NSTrackingArea (Cocoa)
uname -a
- drwxr-xr-x
- ▶ Mac OS X
- ▶ Unix
Serving SVG From a Scala Akka HTTP API
Generating an SVG is straightforward. Serving one reliably through a Scala Akka HTTP API is less forgiving: valid markup can still be downloaded as plain text, cached incorrectly, or exposed to a browser under the wrong security policy. A public diagram endpoint therefore needs an explicit contract covering the response body, media type, caching, validation, and browser access.
I keep practical notes like these in The Coding Journal, where fixes from real projects matter more than polished abstractions. My first version of this endpoint produced attractive diagrams that failed in an email preview and lost cache metadata behind a reverse proxy. The eventual solution combined explicit media types, deterministic content, and tests against the deployed route.
Akka suits the job because its routing model keeps request handling visible while actors provide concurrency and supervision. I separated rendering from transport, stored immutable SVG documents, and used the route to negotiate headers, conditional requests, and errors. That made each layer straightforward to test and inexpensive to change when the endpoint evolved.
Australian teams add some practical context. Developers work in Melbourne, Sydney, Brisbane, and Perth, and users often try APIs from phones on trains, trams, and variable mobile broadband instead of only from an office network. The endpoint should remain useful when latency rises, a proxy intervenes, or the same diagram is requested repeatedly from different devices.
Pick the Right Media Type
SVG is XML, but image/svg+xml is not interchangeable with application/xml or text/xml. The image media type tells browsers, design applications, and document pipelines to treat the entity as a scalable image. It also avoids some security systems interpreting an uploaded drawing as arbitrary XML. Correct markup with the wrong content type still produces incorrect behaviour.
For inline delivery, set the entity’s media type to image/svg+xml and use Content-Disposition: inline. For a deliberate file download, change the disposition to attachment and add a filename such as diagram.svg. These headers control delivery rather than rendering quality, so changing them cannot repair malformed SVG.
Let Akka calculate Content-Length from the final entity where possible. If a filter rewrites the body, recalculate the byte count afterwards; UTF-8 character counts are not byte counts. Avoid adding a charset parameter unless you intend to change that contract and test every consumer.
Build the Akka HTTP Route
I kept each asset in a small case class and returned an explicit HttpResponse. The content type belongs on the entity, while cache, validation, and security headers belong on the response. A service might load the asset from a repository or actor, but the route should not need to know how the SVG was generated.
import akka.http.scaladsl.model._
import akka.http.scaladsl.server.Directives._
import akka.http.scaladsl.server.Route
final case class SvgAsset(body: String, etag: String)
def svgRoute(asset: SvgAsset): Route =
path("assets" / "diagram.svg") {
get {
complete {
HttpResponse(
status = StatusCodes.OK,
headers = List(
HttpHeaders.`Cache-Control`("public, max-age=300"),
HttpHeaders.`Content-Disposition`("inline"),
HttpHeaders.ETag(s"\"${asset.etag}\""),
RawHeader("X-Content-Type-Options", "nosniff")
),
entity = HttpEntity(MediaTypes.`image/svg+xml`, asset.body)
)
}
}
}
The response now advertises image/svg+xml, allows short-lived public caching, supplies a validator, and blocks MIME sniffing. The explicit inline disposition records the intended delivery even though browsers often infer it. This minimal example captures one asset; refresh it safely or resolve it per request in a live service so its body and validator change together. My Mac OS X notes helped me exercise the route locally before packaging it for a server.
Match Headers to the Delivery Context
Header policies depend on how the asset is consumed. Public artwork, exported files, and private user-specific diagrams need different caching and attachment rules:
| Use case | Content-Type | Disposition | Cache policy |
|---|---|---|---|
Browser <img> element |
image/svg+xml |
inline |
public, max-age=300 |
| File download | image/svg+xml |
attachment; filename="diagram.svg" |
no-store |
| Private user diagram | image/svg+xml |
inline |
private, no-store |
| Automated pipeline | image/svg+xml |
inline or attachment |
no-store |
For a public diagram that changes only with its source, a short max-age plus an ETag balances freshness and bandwidth. A client can reuse the cached image while it remains fresh, then send If-None-Match to validate it. When the validator matches, return 304 Not Modified with the validator and no entity.
If bandwidth matters, handle conditional requests whenever you advertise an ETag. Compare quoted entity-tag values consistently and apply the weak comparison rules required for If-None-Match. For private material, use Cache-Control: private, no-store rather than a public directive, and keep sensitive values out of filenames and response headers.
The same drawing may serve a browser and a server-side renderer, but those clients can need different disposition and CORS rules. Decide whether the resource is meant for inline display or downloadable export before opening it broadly.
Protect SVG and Browser Boundaries
SVG can contain scripts, links, embedded images, and external references, so never pass arbitrary user SVG through unchanged. Render trusted elements with a library such as scala-xml, escaping labels and attributes, or sanitise the document against a strict allow-list. When uploads are unavoidable, remove active content and external references before storing or serving them.
Headers provide another layer. X-Content-Type-Options: nosniff reduces MIME confusion, while a restrictive Content-Security-Policy can limit scripts, styles, and external loads. A policy such as default-src 'none'; style-src 'unsafe-inline'; sandbox may suit a simple diagram, but it can also block expected fonts or features. Test the actual asset rather than an empty placeholder.
Cross-origin browser access needs Access-Control-Allow-Origin with an intentional origin policy; never combine a wildcard origin with credentialed requests. A client sending If-None-Match may trigger a preflight, so handle OPTIONS and the relevant allow-method and allow-header values. I also keep Mike Meredith among references for JVM and Akka-related work. Australian businesses covered by the Privacy Act 1988 must also apply the Australian Privacy Principles, including careful handling of personal information in logs, signed URLs, and SVG labels.
Verify Headers at Every Network Hop
Test the route with Akka HTTP’s route test kit, then test the public URL. Assertions should cover the status, Content-Type, disposition, cache directive, and any promised validator. A matching body is insufficient because a proxy can change headers after the application passes its tests. Keep these checks in continuous integration so a refactor cannot silently alter the contract.
Inspect the deployed response with curl -sS -D - -o /dev/null https://api.example.com.au/assets/diagram.svg. Check HEAD as well as GET, and exercise a conditional request to confirm that a matching ETag produces the intended status and empty body. Look for duplicate content-type or content-length values introduced by filters.
I also check one response from a phone on a Melbourne train, where mobile proxies and intermittent connections expose assumptions that office broadband hides. A cached SVG should display promptly, while a failed request should return a clear status instead of a partial image. Inspecting the final hop matters more than trusting a local fixture.
Deploy and Operate the Endpoint
Run the service behind an HTTPS ingress and review the headers after that layer, since ingress and CDNs can rewrite caching, compression, and validation directives. Apply timeouts and request limits to the rendering path. Log status, latency, cache outcome, and response size rather than full SVG bodies; those fields reveal slow or misbehaving consumers without flooding the logs.
An Australian product team may prefer managed cloud hosting to operating its own cluster. Compare regional latency around Sydney and Melbourne, budget recurring AUD charges, and make failover decisions deliberately rather than inheriting a default region. Managed infrastructure reduces operational work, but observability and a clear response contract remain your responsibility.
Deploy one generated diagram behind HTTPS now, add the media type, cache policy, and CORS decision to the release checklist, and verify the same response from a browser and an automated client. Record the route, rendering rule, and validator strategy in a short operational note so the next person can reproduce the contract.
cat ~/interests.json
| Key | Value |
|---|---|
| editor | Terminal-first workflow |
| os | Mac OS X / Unix |
| vcs | Git, distributed version control |
| deploy | Capistrano, cron automation |
| graphics | SVG, Adobe Illustrator troubleshooting |
| networking | IP validation, SSH, VPN |
git log --oneline --reverse
Solving SVG import issues in Adobe Illustrator CS6 and CC
When importing an SVG into Illustrator, the operation fails with an unknown error [CANT]. A workaround for this Adobe-side bug.
Solving NDK build issues on OS X
Troubleshooting native development kit compilation problems on Mac OS X.
Programmatically adding PHP generated TypoScript to the backend configuration
Integrating dynamically generated TypoScript into Typo3 backend setups using PHP.
ArgumentError: Could not parse PKey: no start line
Debugging an SSH key parsing error encountered during deployment.
Validating IP-Addresses in PHP
Using PHP filter functions with flags like FILTER_FLAG_IPV4 and FILTER_FLAG_IPV6, and understanding how filter_var handles reserved IP addresses.
Cocoa: Using NSTrackingArea
A short tutorial on using Cocoa's NSTrackingArea to capture mouseEntered and mouseExited events.
cat ~/contact.txt