1 Artifacts

Artifacts are the fundamental building blocks in Kumori DSL. They define the structure, behavior, and requirements of your application components. By separating interfaces from implementations and providing a rich type system, artifacts enable modular, reusable, and maintainable application design.

A single *.kumori or *.h.kumori file can contain definitions for multiple scoped artifacts or a single unscoped artifact.

1.1 Key Artifact Types

There are three main types of artifacts in Kumori DSL:

  • Component: A deployable unit of code and configuration.
  • Service: A composite artifact that orchestrates other artifacts.
  • Builtin: A reusable contract for common infrastructure or platform features.

This document provides a detailed explanation of each artifact type.

1.2 Component

A component is a deployable unit that encapsulates code, configuration, resources, and service endpoints. Components can define interfaces (contracts) and provide implementations.

Components are declared with the component keyword:

See Component reference for the full definition.

Key features in implementations:

  • Use var ( ... ) to declare intermediate values, referenced as var.Name.
  • Reference interface parameters with interface. (e.g., interface.config.Timeout).
  • Reference implementation parameters with self. (e.g., self.code.MyBackend.size.mincpu).

The compiler (kdsl check) validates artifact correctness, both structurally (via the type system) and with additional rules (e.g., volume mounts must reference a registered resource of type kumori.Volume).

Tip

Modules can provide implementations for third-party interfaces.

1.3 Service

A service orchestrates one or more artifacts (components or other services), mapping its own public interface to the interfaces of the artifacts it uses. Services are the primary mechanism for composing complex application topologies, enabling abstraction and reuse.

Services are declared using the service keyword and, like components, separate their interface from their implementation.

1.3.1 Key Concepts for Services

  • Composition: Services build complex applications by assembling and connecting smaller, reusable artifacts. This enables hierarchical and modular architectures.
  • Abstraction: A service exposes its own interface while hiding the implementation details of the roles it manages.
  • Orchestration: The role block instantiates and configures artifacts, while the connect block wires them together.
  • Interface Mapping: Values from the service’s interface are passed to roles using the interface. prefix (e.g., interface.config.Port).
  • Self-Reference: A service can reference its own implementation fields using the self. prefix (e.g., self.role.EchoServer.config.Port).

Services differ from components in that they do not contain a code block; instead of defining runtime behavior directly, they orchestrate other artifacts that do.

See Service reference for the full definition.

1.4 Builtin

Builtins are a special class of artifacts in Kumori that represent reusable contracts for common infrastructure or platform features.

See Builtins reference for the full definition.

1.5 Deployment

A deployment specifies how artifacts are instantiated and configured in a target environment. It binds concrete implementations to interfaces and provides deployment-specific configuration and resources.

See Deployment reference for the full definition.