README
¶
@.link
. 
· 
The short link service. Named x40, it represents the hex for the "@" character. Created as firebase is going away.
Learn more via the documentation
Usage
Probably, do not, at this point. I'm working on this project instead of full-time work; however, the stability of this project is shaky at best. I'm stabilizing this solution's network APIs and client implementations before the code solution is even reasonably stable.
Understanding this work
This project functions as a demonstration of work. In the future, I will likely cannibalize it for the Practical Introduction to Observability. In it, you can see:
📈 Algorithmic Complexity
You'll see different implementations of the same problem — finding a URL in a set. There is the naive, linear implementation, a binary search implementation, and the one we'd actually use — a very simple hashmap. There are even benchmarks to validate their performance!
📖 Documentation
Learn more about the project, including how to solve specific problems, through the documentation website at x40.dev. This documentation follows the goal-oriented Divio documentation structure to help users of the documentation find what they're looking for quickly, as well as allow developers to add documentation in a structured way that does not become a mess over time.
♾️ Functional Arguments
Look at the BoltDB-backed URL storage and see the variadic argument approach popularized by Dave Cheany and in broad use at Uber.
✍️ Helpful commit messages
Read the commit history to understand my thinking while writing each unit of work. You can see how the thinking has changed over time! You can read more about why I think this is so important
🚆 Infrastructure as Code
Look at the infrastructure as code definitions, using the Tofu (or open-source Terraform implementation) infrastructure tool to create DNS records. See how it is configured to store its state in Google Cloud.
You can also see how we pack the application into a container using a multi-step build via the open-source Podman application. This is built every time we merge to main and store both in GitHub and Google Cloud.
You can check the infrastructure by visiting the managed domains with:
- docs: https://x40.dev
- app: https://x40.link
🤖 Task Runner
Run tasks via the Taskfile from the excellent Task Files project and see how to build the application, including for different operating systems. Get a better understanding of the available tasks via:
$ task --list
Command, or learn more about each task with:
$ task --summary <task>
🧪 Test Driven Development
Take a look around at the files
suffixed with _test. You'll
see the popular "table-driven test" format, with many tests being invoked in parallel to ensure fast execution and concurrency safety.
You'll also see the occasional
benchmark, as well
as well as some
testable examples.
You can learn more on the go website. Some tests even validate concurrency via
the go race detector and go test -race!
❓ Remaining Work
Quite a bit of work remains in this project before it becomes "production-ready!" For example,
- Observability instrumentation (e.g., logs, metrics, traces, profiling)
- Data Backups (e.g. Scheduled, Commit Logs and so on)
- Service Level Management (e.g., SLOs, SLAs)
I have worked with all of these technologies before; however, I have only a limited number of daily hours! Perhaps you can email me, and I can help you find evidence of what you're looking for.
Development & Deployment
See the development documentation or the deployment documentation
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api bootstraps and configures the API stubs connecting the server with the concrete, business logic implementations.
|
Package api bootstraps and configures the API stubs connecting the server with the concrete, business logic implementations. |
|
auth
Package auth provides authentication implementation(s) that can be used to limit access to the (gRPC) server.
|
Package auth provides authentication implementation(s) that can be used to limit access to the (gRPC) server. |
|
auth/jwts
Package jwts provides various different JWT tokens.
|
Package jwts provides various different JWT tokens. |
|
auth/tokens
Package tokens provides an implementation to fetch and manage OAuth2 tokens.
|
Package tokens provides an implementation to fetch and manage OAuth2 tokens. |
|
auth/tokens/seeds
Package seeds provides a way to "seed" a token source; especially one that relies on caching.
|
Package seeds provides a way to "seed" a token source; especially one that relies on caching. |
|
auth/tokens/storage
Package storage provides storage for the cachable token interface.
|
Package storage provides storage for the cachable token interface. |
|
dev
Package dev implements a GRPC server that reads and writes URLs to storage.
|
Package dev implements a GRPC server that reads and writes URLs to storage. |
|
di
Package di provides utilities to help resolve dependencies into valid objects
|
Package di provides utilities to help resolve dependencies into valid objects |
|
Package cfg lists all of the appropriate configuration options, sets defaults and so on.
|
Package cfg lists all of the appropriate configuration options, sets defaults and so on. |
|
package main is the main package of the CLI client
|
package main is the main package of the CLI client |
|
auth
Package auth provides facilities to generate the auth required for connecting to the API
|
Package auth provides facilities to generate the auth required for connecting to the API |
|
Package cmd provides the top level commands for the application
|
Package cmd provides the top level commands for the application |
|
Package server implements the HTTP server that will respond to the requests for URLs, sending the user to the appropriate location (or rejecting the response)
|
Package server implements the HTTP server that will respond to the requests for URLs, sending the user to the appropriate location (or rejecting the response) |
|
message
Package message provides common utilities for working with HTTP messages.
|
Package message provides common utilities for working with HTTP messages. |
|
Package storage provides an interface that can be used to connect to various ways that links can be stored and retrieved.
|
Package storage provides an interface that can be used to connect to various ways that links can be stored and retrieved. |
|
boltdb
Package boltdb implements storage based on the BoltDB database, backed by the filesystem.
|
Package boltdb implements storage based on the BoltDB database, backed by the filesystem. |
|
di
Package di provides a mechanism to select storage providers.
|
Package di provides a mechanism to select storage providers. |
|
firestore
Package firestore implements a storage layer with Google cloud firestore.
|
Package firestore implements a storage layer with Google cloud firestore. |
|
memory
Package memory stores the entire data set in memory.
|
Package memory stores the entire data set in memory. |
|
test
Package test provides a storage implementation designed explicitly for testing
|
Package test provides a storage implementation designed explicitly for testing |
|
yaml
Package yaml provides a read only storage implementation which sources its URLs from a YAML file.
|
Package yaml provides a read only storage implementation which sources its URLs from a YAML file. |
|
Package uid (or unique ID) provides mechanisms of generating the slugs for URLs.
|
Package uid (or unique ID) provides mechanisms of generating the slugs for URLs. |