Part 6: Ensuring Reliability - Validation and Proxies with Parsley

The Challenge of Complexity

As your dependency graph grows, so does the risk of subtle configuration errors. A missing registration or a circular dependency might remain hidden during development, only to manifest as a runtime failure in production. Furthermore, as you add cross-cutting concerns like logging, metrics, or auditing, your core business logic often becomes cluttered with boilerplate code that has nothing to do with the actual domain.

In our previous article, Part 5: Mastering Dependency Resolution in Go with Parsley, we explored advanced ways to resolve services. In this sixth part, we shift our focus to Reliability and Maintainability. We will learn how to use Parsley's Validator to catch configuration issues before your application starts and how to use Generated Proxies to cleanly separate cross-cutting concerns from your business logic.

1. The Validator: Catching Errors Early

The Parsley Validator is a specialized service designed to inspect your ServiceRegistry and identify structural flaws in your dependency graph. It specifically targets two common pitfalls: Missing Dependencies and Circular Dependencies.

Missing Dependencies

A missing dependency occurs when a service's constructor requires another service that hasn't been registered. Without validation, Parsley will attempt to resolve the dependency at runtime and fail, potentially causing a panic if not handled gracefully.

Circular Dependencies

A circular dependency happens when two or more services depend on each other (e.g., A needs B, and B needs A). This creates an infinite loop during resolution, leading to a stack overflow. While Parsley's resolver has runtime checks for this, the Validator provides much better error messaging and allows you to catch the loop during startup or even in a unit test.

Practical Example: Validating at Startup

The best practice is to run the validator immediately after completing your service registrations in main.go.

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

    // ... Register your services and modules ...
    registry.RegisterModule(userModule)
    registry.RegisterModule(orderModule)

    // Validate the complete registry
    registryValidator := registration.NewServiceRegistrationsValidator()
    if err := registryValidator.Validate(registry); err != nil {
        // Fail fast: prevent the application from starting with a broken graph
        log.Fatalf("Service registration failed: %v", err)
    }

    // Proceed to create the resolver
    resolver := resolving.NewResolver(registry)
    // ...
}

Note: For large projects, consider writing a unit test that calls Validate(registry) on your production modules. This ensures that every pull request is checked for dependency integrity before it even reaches the CI environment.

2. Generated Proxies: Intercepting Method Calls

Separation of Concerns is a fundamental principle of clean architecture. However, implementing features like logging or performance tracing often requires modifying every service method, leading to "code rot."

Parsley addresses this through Generated Proxies and Method Interceptors.

The Architecture of Interception

By using the Parsley CLI, you can generate a "Proxy" for any interface. This proxy implements the same interface as your service but wraps the actual implementation. It provides hooks that allow MethodInterceptor services to execute logic before (Enter), after (Exit), or when an error occurs (OnError) during a method call.

Step 1: Annotating and Generating

To enable proxy generation, add the //go:generate annotation to your interface definition.

//go:generate parsley-cli generate proxy
type Greeter interface {
    SayHello(name string)
}

Running go generate ./... will invoke the parsley-cli and produce a greeter.proxy.g.go file containing the GreeterProxy interface and its implementation.

Step 2: Implementing an Interceptor

An interceptor is a standard Go service that implements the features.MethodInterceptor interface.

type loggingInterceptor struct {
    features.InterceptorBase
}

func (l *loggingInterceptor) Enter(_ any, methodName string, params []features.ParameterInfo) {
    log.Printf("Entering method: %s with params: %v", methodName, params)
}

func (l *loggingInterceptor) Exit(_ any, methodName string, results []features.ReturnValueInfo) {
    log.Printf("Exiting method: %s", methodName)
}

Step 3: Wiring it Together

You register the actual implementation, the generated proxy, and the list of interceptors in your registry.

registry.Register(NewGreeter, types.LifetimeTransient)
registry.Register(NewGreeterProxyImpl, types.LifetimeTransient)

// Enable list resolution for interceptors
features.RegisterList[features.MethodInterceptor](registry)
registry.Register(newLoggingInterceptor, types.LifetimeSingleton)

When you resolve GreeterProxy, Parsley injects the real Greeter and all registered interceptors into the proxy. Your business logic remains untouched, yet it is now fully instrumented with logging.

Operational Considerations

Performance of Proxies

Generated proxies use reflection-based parameter mapping to provide context to interceptors. While highly optimized, this does introduce a small overhead compared to direct method calls. For high-frequency, low-latency hot paths, evaluate if the benefits of separation outweigh the performance cost.

Validator in CI/CD

Running the validator is idempotent and fast. It is highly recommended to include a "sanity check" test in your CI pipeline that initializes your production ServiceRegistry and runs the Validator. This prevents "silent" failures where an application builds successfully but fails to start due to a missing environment-specific registration.

Tradeoffs and Limitations

• Binary Size: Generating proxies for every service in a large application will increase your binary size. Only generate proxies for services where cross-cutting concerns are actually needed.
• Complexity of Interceptors: Interceptors have access to method parameters as any types. While flexible, this requires careful handling (and potentially type assertions) if you need to inspect specific values, which can lead to less type-safe code if overused.

3. Building Proxies Manually

The CLI-based workflow covers most use cases, but it depends on running go generate as part of your build. Some environments make that inconvenient: locked-down CI pipelines that reject arbitrary code generation, vendored builds where the source tree is read-only, or teams that want full control over exactly how interceptors are wired into a call. For these cases, Parsley exposes the same building blocks the generator uses through the pkg/features package, so you can hand-write a proxy without any generated code.

Implementing an Interceptor Without Generation

An interceptor built by hand embeds features.InterceptorBase and is initialized with features.NewInterceptorBase, which takes a name and an execution position used to order multiple interceptors.

type loggingInterceptor struct {
    features.InterceptorBase
}

func NewLoggingInterceptor() features.MethodInterceptor {
    return &loggingInterceptor{
        InterceptorBase: features.NewInterceptorBase("logging", 0),
    }
}

func (i *loggingInterceptor) Enter(target any, methodName string, parameters []features.ParameterInfo) {
    log.Printf("entering %s", methodName)
}

func (i *loggingInterceptor) Exit(target any, methodName string, returnValues []features.ReturnValueInfo) {
    log.Printf("exiting %s", methodName)
}

func (i *loggingInterceptor) OnError(target any, methodName string, err error) {
    log.Printf("error in %s: %v", methodName, err)
}

This is the exact interface the generated proxies expect, so hand-written and generated interceptors are interchangeable.

Implementing the Proxy Itself

A manual proxy embeds features.ProxyBase, constructed with features.NewProxyBase, and wraps the target service. Instead of relying on generated dispatch code, you call the interceptor hooks explicitly around the delegated call, after building a MethodCallContext that describes the invocation.

type greeterProxy struct {
    features.ProxyBase
    target Greeter
}

func NewGreeterProxy(target Greeter, interceptors []features.MethodInterceptor) Greeter {
    return &greeterProxy{
        ProxyBase: features.NewProxyBase(target, interceptors),
        target:    target,
    }
}

func (p *greeterProxy) Greet() string {
    callCtx := features.NewMethodCallContext("Greet", nil, nil, "string")

    p.InvokeEnterMethodInterceptors(callCtx)
    result := p.target.Greet()
    p.InvokeExitMethodInterceptors(callCtx)

    return result
}

Registration works the same way as with generated proxies: register the target, the proxy constructor, and the interceptor list, then resolve Greeter to get the intercepted instance.

registry.Register(NewGreeter, types.LifetimeTransient)
registry.Register(NewGreeterProxy, types.LifetimeTransient)

features.RegisterList[features.MethodInterceptor](registry)
registry.Register(NewLoggingInterceptor, types.LifetimeSingleton)

The tradeoff is clear: you write more code than a //go:generate directive would produce, but you decide exactly which methods are intercepted, what the MethodCallContext contains, and where OnError gets invoked. This is a reasonable choice for a handful of hot-path interfaces where you don't want an entire generated file, or for library code that must compile without depending on the parsley-cli toolchain.

Summary

Reliability isn't just about writing bug-free code; it's about building systems that are easy to verify and maintain.

• The Validator provides a safety net, ensuring your dependency graph is sound before your application handles its first request.
• Generated Proxies allow you to implement powerful, reusable cross-cutting concerns without polluting your core domain logic.
• When code generation isn't an option, manual proxies and interceptors built on features.ProxyBase and features.InterceptorBase give you the same interception model with full control.

In the next part of this series, we will dive into Effective Mocking for Testing, where we show how the Parsley CLI can simplify your unit testing workflow by generating sophisticated mocks.

Next Steps

• Install the Parsley CLI: go install github.com/matzefriedrich/parsley/cmd/parsley-cli
• Add a Validator call to your application's startup sequence.
• If your build environment can't run go generate, try implementing a proxy manually with features.ProxyBase and features.InterceptorBase.
• Explore the Validating Service Registrations documentation for more details.