Part 3: Mastering Lifetimes and Scopes in Go with Parsley

Managing State and Lifecycle in Distributed Systems

In modern Go backend development, managing the lifecycle of a service is as critical as its implementation. For instance, a database connection pool should ideally be shared across the entire application to minimize overhead and maintain connection limits. Conversely, an authentication context or a request-specific logger should only exist for the duration of a single HTTP request to avoid state leakage between users.

In the previous article, Part 2: Mastering Service Registration in Go with Parsley, we discussed how to register services using constructors and pre-existing instances. However, registration is only half the story. The other half is determining when these services are created and how long they persist.

Without a structured dependency injection container, developers often end up passing context.Context everywhere or manually managing global variables—both of which increase complexity and hinder testability. Parsley addresses this by providing explicit control over service lifetimes.

Recap: Singleton vs. Registered Instance

In Part 2, we saw two ways to achieve singleton behavior, but they differ in one key aspect: Activation Timing.

• Registered Instance (RegisterInstance): This is an eager singleton. You create the object yourself before registration. Parsley simply stores and provides the pre-existing instance. This is useful for third-party clients or legacy objects.
• Singleton Registration (RegisterSingleton): This is a lazy singleton. You provide a constructor function, and Parsley only calls it the first time the service is requested.

Note: Lazy initialization is generally preferred. It reduces application startup time and ensures that heavy services are only created if they are actually needed by the current execution path.

The Three Pillars of Parsley Lifetimes

Parsley provides three distinct lifetime behaviors to manage your services effectively:

1. Transient: A new instance is created every time the service is requested. This is ideal for lightweight, stateless objects where you want to ensure a clean state for every consumer.
2. Scoped: A single instance is created and reused within a specific scope. In a web server, this usually corresponds to a single HTTP request.
3. Singleton: A single instance is created once and shared throughout the entire application for the lifetime of the resolver.

Architecture: The Role of Scoped Context

The Scoped lifetime is the backbone of request-based architectures. It ensures that all dependencies within a single request—such as a database transaction, a user service, and an audit logger—share the same instance of a request-specific resource.

Parsley manages this by attaching instances to a context.Context. When you create a new scope using resolving.NewScopedContext(ctx), Parsley creates a specialized context that acts as a container for that specific lifecycle.

Practical Example: Observing Service Activation

To demonstrate how lifetimes affect your application, let's create a Greeter service and observe how many times it is instantiated under different scopes.

1. Define the Service

type Greeter interface {
    SayHello(name string)
}

type greeter struct {
    id string
}

func (g *greeter) SayHello(name string) {
    fmt.Printf("Hello, %s! (Instance ID: %s)\n", name, g.id)
}

func NewGreeter() Greeter {
    g := &greeter{}
    // Use the pointer address as a simple unique ID
    g.id = fmt.Sprintf("%p", g)
    fmt.Printf("New Greeter instance activated: %s\n", g.id)
    return g
}

2. Resolve with Scopes

In the following example, we register the Greeter as Scoped. We then resolve it multiple times within two different scopes.

package main

import (
    "context"
    "fmt"
    "github.com/matzefriedrich/parsley/pkg/registration"
    "github.com/matzefriedrich/parsley/pkg/resolving"
)

func main() {
    registry := registration.NewServiceRegistry()

    // Register the constructor with a Scoped lifetime
    _ = registration.RegisterScoped(registry, NewGreeter)

    resolver := resolving.NewResolver(registry)
    ctx := context.Background()

    // --- Scope A ---
    fmt.Println("--- Starting Scope A ---")
    scopeA := resolving.NewScopedContext(ctx)
    g1, _ := resolving.ResolveRequiredService[Greeter](scopeA, resolver)
    g1.SayHello("Alice")

    g2, _ := resolving.ResolveRequiredService[Greeter](scopeA, resolver)
    g2.SayHello("Bob")

    // --- Scope B ---
    fmt.Println("\n--- Starting Scope B ---")
    scopeB := resolving.NewScopedContext(ctx)
    g3, _ := resolving.ResolveRequiredService[Greeter](scopeB, resolver)
    g3.SayHello("Charlie")
}

Output Analysis:

--- Starting Scope A ---
New Greeter instance activated: 0xc0000120a8
Hello, Alice! (Instance ID: 0xc0000120a8)
Hello, Bob! (Instance ID: 0xc0000120a8)

--- Starting Scope B ---
New Greeter instance activated: 0xc0000120b0
Hello, Charlie! (Instance ID: 0xc0000120b0)

Within Scope A, the instance is reused for both "Alice" and "Bob". When we switch to Scope B, Parsley detects a new context and activates a fresh instance.

Operational Considerations

When to Use Transient?

Use transient for services that carry no internal state or are cheap to create. This prevents accidental state leakage between different parts of your application and is the safest default if you are unsure.

When to Use Scoped?

Scoped is the "sweet spot" for backend services. Use it for anything that should be consistent across a single request but isolated from other requests:

• Database transactions
• Request-specific loggers with correlation IDs
• User identity providers

When to Use Singleton?

Use singletons for heavy resources that should persist for the life of the process. Examples include database connection pools (*sql.DB), configuration managers, and external API clients that manage their own internal connection pooling.

Tradeoffs and Limitations

While automated lifetime management reduces boilerplate, it introduces specific engineering responsibilities:

• Context Hygiene: You must ensure that resolving.NewScopedContext is called at the correct entry points (e.g., in a middleware). If you inadvertently use the root context for all resolutions, your scoped services will effectively behave as singletons.
• Memory Management: Singletons stay in memory until the Resolver is destroyed. Be cautious about registering large objects as singletons if they are only needed occasionally.
• Thread Safety: Singleton and Scoped services might be accessed by multiple goroutines concurrently (especially in high-concurrency web servers). Ensure your implementations are thread-safe.

Registry Hierarchies and Isolation

Scoped lifetimes rely on a broader mechanism in Parsley: registries can be arranged in a hierarchy. Calling CreateScope on a registry produces a new types.ServiceRegistry that inherits all registrations from its parent at the time of creation. This is precisely what happens under the hood when resolving.NewScopedContext sets up a scope for a request - the scope can resolve everything the parent registry knows about, plus anything registered specifically within it.

Registrations added to a scope are isolated: they are visible only within that scope, not in the parent or in sibling scopes. This isolation is what makes per-request overrides safe, for example, registering a mock or a request-specific implementation without affecting the global registry.

A related but distinct tool is CreateLinkedRegistry. Unlike CreateScope, a linked registry starts empty—it does not inherit any registrations from its parent. It only shares the parent's internal service-identity state. Linked registries are useful when you want to build an isolated set of registrations for a module and combine it with others later, rather than inheriting an existing service graph.

parentRegistry := registration.NewServiceRegistry()
_ = registration.RegisterSingleton(parentRegistry, NewGlobalConfig)

// A scope inherits existing registrations, such as GlobalConfig
requestScope := parentRegistry.CreateScope()
_ = registration.RegisterScoped(requestScope, NewRequestLogger)

// A linked registry starts empty, sharing only service identity
moduleRegistry := parentRegistry.CreateLinkedRegistry()
_ = registration.RegisterTransient(moduleRegistry, NewModuleHandler)

requestScope can resolve both GlobalConfig and RequestLogger, while parentRegistry can only resolve GlobalConfig. moduleRegistry cannot resolve GlobalConfig at all until it is combined with the parent registry through aggregation.

Combining Registries with NewMultiRegistryAccessor

When your application splits registrations across multiple registries—one per module, for example—you still need a single resolution point. The registration.NewMultiRegistryAccessor function addresses this by aggregating several types.ServiceRegistryAccessor instances into one:

moduleARegistry := registration.NewServiceRegistry()
_ = registration.RegisterSingleton(moduleARegistry, NewBillingService)

moduleBRegistry := registration.NewServiceRegistry()
_ = registration.RegisterSingleton(moduleBRegistry, NewNotificationService)

accessor := registration.NewMultiRegistryAccessor(moduleARegistry, moduleBRegistry)
resolver := resolving.NewResolver(accessor)

Parsley searches the provided registries in order and resolves from the first one containing a matching registration. This makes the accessor order significant: placing a specialized registry before a general one lets it override a shared registration, which is useful for testing or for modules that need to substitute a default implementation.

Combined, CreateScope/CreateLinkedRegistry and NewMultiRegistryAccessor give you two complementary tools: scopes and linked registries control isolation within a hierarchy, while the multi-registry accessor lets you flatten several independent registries into a single resolution path.

Summary

Understanding lifetimes and scopes is essential for building scalable Go applications. By leveraging Transient, Scoped, and Singleton behaviors, you can ensure that your services are created at the right time and shared only when appropriate, leading to cleaner code and more predictable resource usage.

In the next part of this series, we will explore Advanced Registration Patterns, where we discuss how to organize your services into modules and use custom factory functions.

Next Steps

• Explore the Lifetime Scopes documentation for more details.
• Review your application's main.go and determine which services could benefit from a Scoped lifetime.
• Read the Registry Hierarchy and Multi-Registry Aggregation documentation if your application is split into modules with separate registries.