Forem: Aman

Caddy + Cloudflare DNS: Wildcard SSL Without the Pain

Aman — Sat, 14 Feb 2026 11:00:15 +0000

Wildcard certs (*.example.com) require DNS-01 challenge. HTTP challenge can't prove you own every subdomain. If your DNS is on Cloudflare, that means building Caddy yourself, since the default binary ships without DNS provider modules.

This guide walks through the full setup: custom build, secure token storage, and a working Caddyfile.

Why a Custom Build?

Caddy's DNS provider support ships as external modules that get compiled in at build time. The official xcaddy tool exists exactly for this. It's a thin wrapper around go build that handles module injection cleanly.

1. Install Base Caddy

Follow the official install docs for your distro. Don't skip this step even though we're replacing the binary later. The package install handles systemd unit setup, user/group creation, and directory structure.

2. Install Go

Avoid your distro's package manager here; Go versions in system repos tend to lag. Get the latest from go.dev/doc/install.

3. Install xcaddy

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

If xcaddy isn't found after this, your $GOPATH/bin isn't in $PATH:

export PATH=$PATH:$(go env GOPATH)/bin

4. Build Caddy with the Cloudflare Module

xcaddy build --with github.com/caddy-dns/cloudflare

This drops a caddy binary in your current directory. Verify the module made it in:

./caddy list-modules | grep cloudflare
# dns.providers.cloudflare

If you see that, the build worked.

5. Replace the System Binary

sudo systemctl stop caddy
sudo mv ./caddy $(which caddy)

6. Store the Cloudflare Token Securely

Don't put the token directly in your Caddyfile — it's too easy to accidentally commit or expose. The cleaner approach is a systemd environment file that Caddy reads at startup.

Tell systemd about it:

sudo systemctl edit caddy.service

Add and save:

[Service]
EnvironmentFile=/etc/caddy/cloudflare.env

Create the file and lock it down:

echo "CLOUDFLARE_API_TOKEN=your_token_here" | sudo tee /etc/caddy/cloudflare.env
sudo chmod 400 /etc/caddy/cloudflare.env
sudo systemctl daemon-reload

On the Cloudflare side, create a scoped API token with only Zone > DNS > Edit permissions for your specific zone — not a global API key. If it ever leaks, the blast radius is contained.

7. Update the Caddyfile

{
  acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
  email you@example.com
}

*.example.com {
  reverse_proxy localhost:8080
}

The {env.CLOUDFLARE_API_TOKEN} syntax reads the value at runtime, so the token never sits in the config file itself.

8. Start Caddy

sudo systemctl start caddy && journalctl -u caddy -f

Caddy will create a DNS TXT record in your Cloudflare zone, validate with Let's Encrypt, issue the wildcard cert, then clean up the TXT record. The whole thing is automatic — once it's running you won't think about certificates again.

Troubleshooting

Module isn't listed: run caddy list-modules | grep dns. If nothing shows up, the binary replacement didn't take. Double-check with which caddy that you replaced the right one.

Certificate issuance hanging: Let's Encrypt polls for DNS propagation, which can take a couple of minutes even on Cloudflare. Wait before assuming something is broken.

Token permission error: verify the token has Zone > DNS > Edit and is scoped to the correct zone. Cloudflare's token model is granular and easy to misconfigure.

Stop Mixing Up Unmodifiable Views and Immutable Lists

Aman — Wed, 24 Dec 2025 15:23:32 +0000

In Java, the word immutable gets thrown around too casually. That is fine until you deal with shared state, concurrency, or domain objects that must behave predictably. At that point, confusing a read-only view with a truly immutable collection becomes a real problem.

Two APIs usually sit at the center of this confusion:

Collections.unmodifiableList()
List.copyOf()

They look similar on the surface, but internally they behave very differently.

1. `Collections.unmodifiableList()`: Read-Only, Not Immutable

Collections.unmodifiableList() does not create a new list. It wraps an existing one.

Think of it as a guardrail. It stops callers from modifying the list through that reference and nothing more.

What it actually does

Wraps an existing List
Implements the List interface
Throws UnsupportedOperationException for mutation methods like add, remove, and set
Continues to point to the same underlying data

That last point is the important one.

List<String> internalData = new ArrayList<>(List.of("A", "B"));
List<String> publicView = Collections.unmodifiableList(internalData);

internalData.add("C");
// publicView now contains "C"

No rules were broken.

The wrapper behaved exactly as designed.

Why this matters

The data is still mutable
Any code holding the original list can change it
All "unmodifiable" views will reflect those changes

When this is acceptable

You want to protect a method boundary
You fully own the backing list
The list will never be mutated again

When it is a bad idea

Shared state
Cached data
Configuration
Multi-threaded access

Verdict: This protects the API, not the data. It does not give you immutability, and it does not make your code thread-safe.

2. `List.copyOf()`: A Real Snapshot

List.copyOf() was added in Java 10 and solves the problem properly.

Instead of wrapping, it copies.

What it actually does

Creates a new list instance
Copies all elements into a private internal structure
Removes any connection to the source list

List<String> internalData = new ArrayList<>(List.of("A", "B"));
List<String> frozenData = List.copyOf(internalData);

internalData.add("C");
// frozenData is still ["A", "B"]

Once created, the list cannot change, no matter what happens to the original.

Why this matters

No shared mutable state
Safe to cache
Safe to share across threads
Predictable behavior

Verdict: This is actual immutability.

Key Differences That Matter in Practice

Aspect	`unmodifiableList()`	`List.copyOf()`
Data copy	No	Yes
Backed by source	Yes	No
Reacts to source changes	Yes	No
Null elements	Allowed	Throws `NullPointerException`
Thread-safe by default	No	Yes
Cost	O(1)	O(n)

A note on `null`

List.copyOf() (like List.of()) rejects null values:

List.copyOf(List.of("A", null)); // NullPointerException

This is intentional. Failing early is better than chasing random NullPointerExceptions deep inside business logic.

A Practical Rule of Thumb

Ask yourself these questions:

Is this list cached, shared, or read by multiple threads? Use List.copyOf().
Am I returning internal state from a class? Use List.copyOf() to avoid representation exposure.
Am I only trying to stop callers from modifying a list I fully control? Collections.unmodifiableList() may be acceptable if you truly understand the risk.

The cost of copying is almost always insignificant compared to the cost of debugging race conditions.

Bottom Line

Unmodifiable protects the interface
Immutable protects the data

Most modern Java systems need the second one.
If correctness matters, stop wrapping and start copying.

Don’t Let Your Singleton Break! Here’s How to Make It 100% Thread-Safe in Java

Aman — Fri, 01 Nov 2024 17:11:24 +0000

In this post, we’ll explore several ways to implement a thread-safe singleton in Java, including eager initialization, double-checked locking, and the inner static class approach. We’ll also discuss why the final keyword is beneficial in ensuring the integrity of a singleton.

Why Use a Singleton?

Singletons are useful when you need exactly one instance of a class throughout the application. Common use cases include managing shared resources such as logging, configuration, or connection pools. A singleton ensures that multiple requests to access a class share the same instance, rather than creating new ones.

1. Eager Initialization: The Simplest Singleton

The eager initialization pattern creates the singleton instance when the class is loaded. This is straightforward and ensures thread safety because the instance is created when the class is loaded by the JVM.

public final class Singleton {
    // Instance is created at class loading time
    private static final Singleton INSTANCE = new Singleton();

    // Private constructor prevents instantiation from other classes
    private Singleton() {}

    public static Singleton getInstance() {
        return INSTANCE;
    }
}

Pros and Cons of Eager Initialization

Pros:

Simple and thread-safe by default, as the JVM guarantees class initialization is thread-safe.
No need for synchronization or additional complexity.

Cons:

Instance is created whether it’s used or not, which can lead to wasted resources if the singleton is never needed.

When to Use It: Eager initialization is best when the singleton class is lightweight and you’re certain it will be used during the application’s runtime.

2. Lazy Initialization with Double-Checked Locking

In cases where you want to delay the creation of the singleton until it’s needed (known as lazy initialization), double-checked locking provides a thread-safe solution. It uses minimal synchronization and ensures the instance is created only when it’s accessed for the first time.

public final class Singleton {  // Marked as final to prevent subclassing

    // volatile ensures visibility and prevents instruction reordering
    private static volatile Singleton instance;

    // Private constructor prevents instantiation from other classes
    private Singleton() {}

    public static Singleton getInstance() {
        if (instance == null) {               // First check (no locking)
            synchronized (Singleton.class) {   // Locking
                if (instance == null) {        // Second check (with locking)
                    instance = new Singleton();
                }
            }
        }
        return instance;
    }
}

Why Double-Checked Locking Works

First Check: The if (instance == null) check outside the synchronized block allows us to avoid locking every time getInstance() is called. This improves performance by bypassing the synchronized block for future calls after initialization.
Synchronized Block: Once instance is null, entering the synchronized block ensures only one thread creates the Singleton instance. Other threads that reach this point must wait, preventing race conditions.
Second Check: Inside the synchronized block, we check instance again to ensure no other thread has initialized it while the current thread was waiting. This double-check ensures only one Singleton instance is created.

Why `volatile` is Needed

The volatile keyword is essential in the double-checked locking pattern to prevent instruction reordering. Without it, the statement instance = new Singleton(); might appear completed to other threads before it’s fully initialized, leading to a partially constructed instance being returned. volatile guarantees that once instance is non-null, it’s fully constructed and visible to all threads.

Why `final` is Good Practice

The final keyword is used here to prevent subclassing. Marking the Singleton class as final has two primary benefits:

Prevents Subclassing: By making the class final, we prevent other classes from extending it. This ensures that only one instance of the Singleton class can exist since subclassing could lead to additional instances, which would break the singleton pattern.
Signals Immutability: final serves as a clear indicator to other developers that the singleton class is intended to be immutable and should not be extended. This makes the code easier to understand and maintain.

In short, final reinforces the singleton’s integrity and helps avoid unexpected behavior from subclassing.

Pros and Cons of Double-Checked Locking

Pros:

Lazy initialization saves resources by delaying creation until needed.
Minimal synchronization overhead due to double-checking.

Cons:

Slightly more complex and requires volatile for safety.
Can be overkill for simpler singleton needs where eager initialization is sufficient.

When to Use It: This pattern is useful when the singleton class is resource-intensive and might not always be needed, or when performance in a multithreaded environment is a concern.

3. Inner Static Class: A Cleaner Lazy Initialization Alternative

An alternative thread-safe approach to lazy initialization is the inner static class pattern. This leverages Java’s class-loading mechanism to initialize the singleton instance only when it’s needed, without explicit synchronization.

public final class Singleton {
    private Singleton() {}

    // Inner static class responsible for holding the Singleton instance
    private static class SingletonHelper {
        private static final Singleton INSTANCE = new Singleton();
    }

    // Public method to provide access to the instance
    public static Singleton getInstance() {
        return SingletonHelper.INSTANCE;
    }
}

How the Inner Static Class Works

In this pattern, the SingletonHelper class is only loaded when getInstance() is called for the first time. This triggers the initialization of INSTANCE, ensuring lazy loading without requiring synchronized blocks.

Pros and Cons of Inner Static Class

Pros:

Thread-safe without the need for volatile or synchronized blocks.
Simple and clean, with lazy initialization by design.

Cons:

Slightly less intuitive for new developers unfamiliar with Java’s class-loading mechanics.

When to Use It: Use the inner static class pattern when you want lazy initialization with clean, maintainable code. This is often the preferred choice due to simplicity and thread-safety.

Wrapping Up

We’ve looked at three popular ways to implement a thread-safe singleton in Java:

Eager Initialization: Best for simple cases where the singleton is lightweight and will always be used.
Double-Checked Locking: Great for performance-sensitive, multithreaded environments with a need for lazy initialization.
Inner Static Class: A clean and thread-safe approach to lazy initialization using Java’s class-loading behavior.

Each approach has its strengths and is suited for different scenarios. Try them out in your own projects and see which one works best for you! Let me know in the comments if you have a preferred approach or any questions.

Happy coding! 👨‍💻👩‍💻

Transform Your Java Code: Unlock the Power of Immutability with Lombok in Just Minutes!

Aman — Sun, 25 Aug 2024 17:50:27 +0000

Why Immutable Classes?

Immutable classes are beneficial because they are inherently thread-safe, easy to reason about, and prevent accidental changes to the object's state. An immutable object’s state cannot be modified after it is created, making it a valuable design pattern, especially in multi-threaded environments.

Traditional Approach to Creating an Immutable Class

Consider the following Employee class:

final class Employee {
    private final long id;
    private final String name;
    private final double salary;

    public Employee(long id, String name, double salary) {
        this.id = id;
        this.name = name;
        this.salary = salary;
    }

    public long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public double getSalary() {
        return salary;
    }
}

In this traditional approach:

The class is marked final to prevent subclassing.
All fields are private and final, ensuring they cannot be changed after initialization.
Only getter methods are provided to access the field values.

While this approach works well, it involves writing boilerplate code for constructors, getters, and sometimes equals, hashCode, and toString methods.

Using Lombok to Eliminate Boilerplate

Lombok can drastically reduce the amount of code you need to write. Here's how you can achieve the same functionality with Lombok:

import lombok.AllArgsConstructor;
import lombok.Getter;

@AllArgsConstructor
@Getter
final class Employee {
    private final long id;
    private final String name;
    private final double salary;
}

This version uses Lombok annotations to generate the constructor and getters automatically:

@AllArgsConstructor generates a constructor with all fields as parameters.
@Getter generates getter methods for each field.

Simplifying Even Further with `@Value`

Lombok’s @Value annotation is a more powerful alternative that combines multiple features to create an immutable class:

import lombok.Value;

@Value
class Employee {
    long id;
    String name;
    double salary;
}

With @Value, Lombok automatically:

Makes the class final.
Makes all fields private and final by default.
Generates an all-arguments constructor.
Generates getters for all fields.
Implements equals, hashCode, and toString methods.

This reduces your class definition to just the fields, with all the necessary code automatically generated.

Handling Field Updates with `@With`

Immutable objects do not allow modification of their state. However, in certain cases, you may need to create a modified copy of the object, such as updating an employee's salary. Without Lombok, this could look like:

@Value
class Employee {
    long id;
    String name;
    double salary;
}

class Main {
    public static void main(String... args) {
        var emp = new Employee(1L, "Aman", 10_000.0);
        emp = updateSalary(emp, 12_0000.0);
    }

    public Employee updateSalary(Employee emp, long newSalary) {
        return new Employee(emp.getId(), emp.getName(), newSalary);
    }
}

This is straightforward but tedious, especially when dealing with classes that have many fields.

Lombok's @With annotation simplifies this:

import lombok.Value;
import lombok.With;

@Value
class Employee {
    long id;
    String name;
    @With double salary;
}

class Main {
    public static void main(String... args) {
        var emp = new Employee(1L, "Aman", 10_000.0);
        emp = updateSalary(emp, 12_0000.0);
    }

    public Employee updateSalary(Employee emp, double newSalary) {
        return emp.withSalary(newSalary);
    }
}

The @With annotation generates a method that returns a new instance of the class with the specified field updated, leaving the rest unchanged.

The Final De-lomboked Version

The de-lomboked version of our Employee class (i.e., what Lombok generates under the hood) would look like this:

final
class Employee {
    private final long id;
    private final String name;
    private final double salary;

    public Employee(long id, String name, double salary) {
        this.id = id;
        this.name = name;
        this.salary = salary;
    }

    public Employee withSalary(double salary) {
        return this.salary == salary ? this : new Employee(this.id, this.name, salary);
    }

    public long getId() {
        return this.id;
    }

    public String getName() {
        return this.name;
    }

    public double getSalary() {
        return this.salary;
    }

    @Override
    public boolean equals(final Object o) {
        if (o == this) return true;
        if (!(o instanceof Employee)) return false;
        final Employee other = (Employee) o;
        if (this.getId() != other.getId()) return false;
        final Object this$name = this.getName();
        final Object other$name = other.getName();
        if (this$name == null ? other$name != null : !this$name.equals(other$name)) return false;
        return Double.compare(this.getSalary(), other.getSalary()) == 0;
    }

    @Override
    public int hashCode() {
        final int PRIME = 59;
        int result = 1;
        final long $id = this.getId();
        result = result * PRIME + (int) ($id >>> 32 ^ $id);
        final Object $name = this.getName();
        result = result * PRIME + ($name == null ? 43 : $name.hashCode());
        final long $salary = Double.doubleToLongBits(this.getSalary());
        result = result * PRIME + (int) ($salary >>> 32 ^ $salary);
        return result;
    }

    @Override
    public String toString() {
        return "Employee(id=" + this.getId() + ", name=" + this.getName() + ", salary=" + this.getSalary() + ")";
    }
}

Common Pitfalls When Using Lombok for Immutability

While Lombok simplifies creating immutable classes, it's important to note some potential pitfalls:

Mutable Collections: If your class contains mutable collections (like List or Map), Lombok’s @Value annotation won’t protect you from modifications to these collections. Consider using immutable versions like Collections.unmodifiableList or List.of() for initialization.
Complex Objects: If your class fields are complex objects that themselves are mutable, the immutability of the class is compromised. Ensure that all fields are either primitive, immutable objects, or properly encapsulated to prevent mutation.

Performance Considerations

While immutability offers significant benefits, it’s important to consider the performance impact, particularly in scenarios involving frequent updates:

Memory Usage: Creating new instances every time a change is needed can lead to higher memory usage. However, this trade-off is often worth it for the benefits of thread safety and reduced complexity.
Garbage Collection: The creation of multiple short-lived objects can put additional pressure on the garbage collector. Ensure that your application’s memory management is optimized for such scenarios.

Conclusion

Lombok's @Value and @With annotations offer a powerful and concise way to create immutable classes in Java, eliminating the need for boilerplate code and making your code more readable and maintainable. By leveraging these annotations, you can focus on the logic of your application rather than the mechanics of class design.

Wrapping useContext in custom hook and HOC adapter

Aman — Tue, 10 Jan 2023 16:34:53 +0000

You have a component and there are lots of nested sub-component. There is need to share the state between the sub component. We create a state in parent component and pass down the state to the nested component.

It is very inconvenient if there is vary few sub-component is using the state and it is nested level down.

Other way to solve this problem is useContext Hook.
wrap the parent component with ContextProvider and now we can use the state anywhere in sub-component.

If you have a lot of Context.The code readability decreases and it gets ugly.

One of the way to make it better is using custom hook and Provider HOC on top of the useContext.

Let's say we have a isAuth state to be shared in sub-component.

Create AuthProvider HOC wrapper and useAuth hook

const AuthContext = React.useContext<boolean>(false);

export type AuthProviderProps = {
   children: JSX.Element | JSX.Element[];
   isAuth: boolean;
}
export const AuthProvider = ({children, isAuth} : AuthProviderProps) => {
   return (<AuthContext.Provider value={isAuth}>
      {children}
   </AuthContext.Provider>);
}

export const useAuth = () => {
   const isAuth = React.useContext(AuthContext);
   return { isAuth };
}

How to use the hook and HOC

Use the AuthProvider HOC in parent component to wrap the child components.


const [isAuth, setIsAuth] = React.useState<boolean>(false);
....
....
return (
   <AuthProvider isAuth={isAuth}>
      ...
      child components
      ...
   </AuthProvider>);

Somewhere in nested child component, use the useAuth hook to access the isAuth state.

const {isAuth} = useAuth();
...
...
return <div> You are {isAuth ? "" : "not"} authenticated</div>

Forem: Aman

Caddy + Cloudflare DNS: Wildcard SSL Without the Pain

Why a Custom Build?

1. Install Base Caddy

2. Install Go

3. Install xcaddy

4. Build Caddy with the Cloudflare Module

5. Replace the System Binary

6. Store the Cloudflare Token Securely

7. Update the Caddyfile

8. Start Caddy

Troubleshooting

Stop Mixing Up Unmodifiable Views and Immutable Lists

1. Collections.unmodifiableList(): Read-Only, Not Immutable

What it actually does

Why this matters

When this is acceptable

When it is a bad idea

2. List.copyOf(): A Real Snapshot

What it actually does

Why this matters

Key Differences That Matter in Practice

A note on null

A Practical Rule of Thumb

Bottom Line

Don’t Let Your Singleton Break! Here’s How to Make It 100% Thread-Safe in Java

Why Use a Singleton?

1. Eager Initialization: The Simplest Singleton

Pros and Cons of Eager Initialization

2. Lazy Initialization with Double-Checked Locking

Why Double-Checked Locking Works

Why volatile is Needed

Why final is Good Practice

Pros and Cons of Double-Checked Locking

3. Inner Static Class: A Cleaner Lazy Initialization Alternative

How the Inner Static Class Works

Pros and Cons of Inner Static Class

Wrapping Up

Transform Your Java Code: Unlock the Power of Immutability with Lombok in Just Minutes!

Why Immutable Classes?

Traditional Approach to Creating an Immutable Class

Using Lombok to Eliminate Boilerplate

Simplifying Even Further with @Value

Handling Field Updates with @With

The Final De-lomboked Version

Common Pitfalls When Using Lombok for Immutability

Performance Considerations

Conclusion

Wrapping useContext in custom hook and HOC adapter

Create AuthProvider HOC wrapper and useAuth hook

How to use the hook and HOC

1. `Collections.unmodifiableList()`: Read-Only, Not Immutable

2. `List.copyOf()`: A Real Snapshot

A note on `null`

Why `volatile` is Needed

Why `final` is Good Practice

Simplifying Even Further with `@Value`

Handling Field Updates with `@With`