1 Using External Artifacts (another module)

This tutorial shows how to use a component/service defined in another module.

There are two common patterns:

Remote dependency (versioned): the module is downloaded into your module cache.
Local dependency (filesystem or .vendor): used during development without publishing.

The DSL import mechanism is the same in both cases: you import a package path and then reference the artifact.

1.1 Add the dependency in `kumori.mod.json`

Example: depend on a module (aliased) and pin a version.

{
  "spec": "kumori/module/v1",
  "module": "kumori.tutorials/consumer",
  "kumori": "0.0.1",
  "version": "0.0.1",
  "requires": [
    {
      "target": "kumori.examples/dependency",
      "version": "1.2.3",
      "alias": "example-dependency"
    }
  ]
}

Typical command to create this entry:

kdsl mod dep kumori.examples/dependency@1.2.3 --alias example-dependency --download

1.1.1 Remote dependency from a GitHub URL

If your dependency is hosted in GitHub, you can depend on it directly using its module path (for example github.com/<org>/<repo>).

Example kumori.mod.json using a GitHub module path:

{
  "spec": "kumori/module/v1",
  "module": "kumori.tutorials/consumer",
  "kumori": "0.0.1",
  "version": "0.0.1",
  "requires": [
    {
      "target": "github.com/acme/echo-module",
      "version": "v1.0.0",
      "alias": "acme-echo"
    }
  ]
}

Then download it:

kdsl mod dep github.com/acme/echo-module@v1.0.0 --alias acme-echo --download

Once downloaded, imports use the alias prefix:

import "acme-echo/service"

1.2 Import the dependency package in your Kumori DSL

When you use an alias, you import using the alias prefix:

import (
    "example-dependency/service"
    "kumori"
)

This imports the service package from the kumori.examples/dependency module. In practice, everything under the service/ folder in that module is now accessible under the service package.

1.3 Reference the external artifact from a deployment

This deployment targets an artifact defined in the imported package (service.EchoServer).

import (
    "example-dependency/service"
    "kumori"
)

deployment {
    name       "external-echo"
    artifact   service.EchoServer
    resilience 10

    config {
        Port     8080
        Response "Hello World"
        Scale    3
    }

    resource {
        Port   kumori.Port("my-port")
        Volume kumori.Ephemeral(33G)
    }
}

1.4 Local development alternatives

1.4.1 Local dependency (absolute path)

You can add a local module by pointing requires[].target to an absolute path (recommended to also set an alias). See Dependency Management.

1.4.2 `.vendor` directory

You can place a module under a .vendor/ folder at the root of your module so kdsl can resolve it without downloading. See Dependency Management.

1.5 Notes

Imports reference packages, not whole repositories. If your dependency exports artifacts from a package like service/, import that package.
If you later remove the dependency, remember to remove/update imports that use its alias.