systems and capabilities

[amitu]

We can extend the https://github.com/orgs/fastn-stack/discussions/1470 discussion, by saying we have "systems", and design-system is one such system, and systems can be required or provided.

We introduce a new package type called "system" (system: true, can be added in any fastn.package).

So design-system package is created with:

-- import: fastn
-- fastn.package: fastn-community.github.io/design-system
system: ds

Any package can require this:

-- import: fastn
-- fastn.package: fastn-community.github.io/header
;; requires can contain one or more comma separated values
requires: fastn-community.github.io/design-system

Or we can do (this our decision):

-- fastn.dependency: fastn-community.github.io/design-system
system: ds

In system: ds we are saying ds is auto imported and available to all modules inside this package.

And the main package has to provide/meet all requirements or all packages used directly or indirectly:

-- import: fastn
-- fastn.package: amitu.com

-- fastn.dependency: fastn-community.github.io/design-system
provides-via: amitu.com/ds

;; doc-site itself imports headers, so without the dependency above it would have complained
-- fastn.dependency: fastn-community.github.io/doc-site

If any dependency of amitu.com accesses ds auto imported global variable, they will see amitu.com/ds.

The actual contract would be kept in a special module system in every system package, eg fastn-community.github.io/design-system/system exists as a module, and amitu.com/ds has to now "implement" this module.

The minimal ds.ftd in amitu.com would be:

-- import: fastn-community.github.io/design-system/system
exposing: *

Tho if that is all you want you can also do:

-- fastn.dependency: fastn-community.github.io/design-system
provides-via: fastn-community.github.io/design-system/system

And avoid creating that 2 line file. Tho all our templates will include the two line file, possibly overwrite some common settings like site name, logo etc.

[amitu]

Case study: TODO App

Say we are creating a reusable todo app, community.fastn.com/todos it needs some custom settings, say number of todos per page. The package also needs design system, so it can build UI that is consistent with rest of UI. Finally it needs access to database.

fastn community already has two popular systems: community.fastn.com/design-system (which provides ds.button, ds.color-scheme, ds.site-logo etc) and community.fastn.com/postgresql-db (which provides db.db-url, db.schema-name etc). To store todo app specific configurations we the todo app has to also become a system package, and create a config.ftd file.

-- integer todos-per-page:

And declares itself a system (FASTN.ftd of todo app):

-- import: fastn
-- fastn.package: community.fastn.com/todos
system: community.fastn.com/todos/config

-- fastn.dependency: community.fastn.com/design-system
requires: ds

-- fastn.dependency: community.fastn.com/postgresql-db
requires: db

Now if amitu.com wants to use two instances of community.fastn.com/todos it has to do this:

Alternative 1:

-- import: fastn
-- fastn.package: amitu.com

-- fastn.provider ds: community.fastn.com/design-system
via: amitu.com/ds

-- fastn.provider db: community.fastn.com/postgresql-db
via: amitu.com/db

-- fastn.provider todo-config-1: community.fastn.com/todos
via: amitu.com/todo-config-1

-- fastn.provider todo-config-2: community.fastn.com/todos
via: amitu.com/todo-config-2

-- fastn.app: /todos/
dependency: community.fastn.com/todos
provides: $ds, $db, $todo-config-1

-- fastn.app: /work-todos/
dependency: community.fastn.com/todos
provides: $ds, $db, $todo-config-2

Alternative 2:

-- import: fastn
-- fastn.package: amitu.com

-- fastn.dependency: community.fastn.com/design-system
via: amitu.com/ds

-- fastn.dependency: community.fastn.com/postgresql-db
via: amitu.com/db

-- fastn.app: /todos/
dependency: community.fastn.com/todos
config:  amitu.com/todo-config-1

-- fastn.app: /work-todos/
dependency: community.fastn.com/todos
config:  amitu.com/todo-config-2

[amitu]

What if user wants the two todo apps to use different dbs?

-- import: fastn
-- fastn.package: amitu.com

-- fastn.dependency: community.fastn.com/design-system
via: amitu.com/ds

-- fastn.dependency: community.fastn.com/postgresql-db
via: amitu.com/db

-- fastn.app: /todos/
dependency: community.fastn.com/todos
config: amitu.com/todo-config-1

-- fastn.app: /work-todos/
dependency: community.fastn.com/todos
config: amitu.com/todo-config-2
postgresql-db: amitu.com/work-db

By default we pass the "global systems" to everyone, but we can overwrite that by using the system alias keys like the last line shown above.

[amitu]

To store todo app specific configurations we the todo app has to also become a system package, and create a config.ftd file.

We can ignore and and say all app: true are automatically require config. We can say app: config.ftd if we want user to pick custom file names where they would specify configuration (not sure about this, convention is better than configuration in this case I feel).

[amitu]

We can also use systems as a capability token, like to make http request, technically we do not need any setting but we can make our processor require a capability token which is only available if a dependency has requested http system and main package has passed that system to the dependency.

Maybe we can also allow an optional system requirement, main will have to say dependency not allowed to make it clear it needs a dependency and main as explicitly decided not to pass it.

Capability can also decide to what domain, and how many request per day/page view, total size etc etc.

You need cookie, you ask for it and so on.

[amitu]

Since we are going to require many small files for each capability and it may get cluttered, maybe we should also allow:

-- module foo:

<Content of module>

As inline modules in FASTN.ftd. To refer to them in capability statements (via and config) we can use $foo syntax.

[amitu]

If a capability does not require any configuration, eg http, maybe we can say via: default. Default config we can just leave out if none of the properties are required.

[amitu]

Since we are talking of capabilities, maybe passing all capabilities that are imported to every dependency is not a good default. Maybe we should explicitly name requested-capability-alias: true | <module-reference> to everything needing it. We will pass true to use global capability configuration and <module-reference> if we want to specify any specifically configured capability to any dependency or app.

[amitu]

amitu.com

FASTN.ftd

-- import: fastn
-- fastn.package: amitu.com

-- fastn.dependency: ds.fastn.com
provided-via: amitu.com/ds

-- fastn.dependency: doc-site.com

ds.ftd

-- import: ds.fastn.com
export: <name-of-each-symbol>, <excluding-any-overwrites>

<any overwrites>

Note: it is not necessary amitu.com/ds will be implemented using ds.fastn.com, it can also use other packages as base package.

-- import: <some-other-package-implementing-ds>
export: <name-of-each-symbol>, <excluding-any-overwrites>

<any overwrites>

Also if there are no overwrites, the FASTN.ftd can directly point to the other package (no need of amitu.com/ds.ftd file now):

-- import: fastn
-- fastn.package: amitu.com

-- fastn.dependency: some-other-package-implementing-ds

-- fastn.dependency: ds.fastn.com
provided-via: some-other-package-implementing-ds

-- fastn.dependency: doc-site.com

ds.fastn.com

-- import: fastn
-- fastn.package: ds.fastn.com
system: ds
system-is-confidential: false

This will lead to auto import of the actual module that implements ds.fastn.com as the alias ds.

doc-site.com

-- import: fastn
-- fastn.package: doc-site.com

-- fastn.dependency: ds.fastn.com
required-as: ds
provided-via: some-other-package-implementing-ds

-- fastn.dependency: some-other-package-implementing-ds

The provided-via would only be used if this package was the main package.

some-other-package-implementing-ds

Should also say it implements ds.fastn.com:

```ftd
-- import: fastn
-- fastn.package: some-other-package-implementing-ds
implements: ds.fastn.com

[Arpita-Jaiswal]

Some thoughts

Can we omit the system header from the fastn.package?

The system header right now only gives auto-import alias. What if we can do this:

-- fastn.package: ds.fastn.com
;; system-is-confidential: false ;; make this default

-- fastn.dependency: ds.fastn.com
provided-via: other-package/ds

This helps us to give provided-via for any package besides the system package. Every package becomes like a system package only.

What if we allow the user to overwrite some components of the package but not all

In FASTN.ftd

-- fastn.dependency: ds.fastn.com
required-as: overwritable

-- fastn.dependency: ds.fastn.com as not-overwritable

In index.ftd

-- import: overwritable
-- import: not-overwritable

-- overwritable.heading-small: Some heading component which can be overwritten
-- not-overwritable.heading-small: Some heading component which can't be overwritten

Can we use overwritable: true instead of required-as: <alias>?

-- fastn.dependency: ds.fastn.com
required-as: ds

Here required-as serves no purpose besides telling the user package that it's ready to accept/overwrite the dependency module and since we have as to give an alias, we can probably do:

-- fastn.dependency: ds.fastn.com as ds
overwritable: true

[amitu]

Can we omit the system header from the fastn.package?

We possibly can, technically, but let's not do this as system gives a useful meta data around which we can implement many features. Each required-as, etc are creating a "cluster of packages" which are compatible with each other, and we will need to name this cluster, so a single package, which marks itself system: true, can be used to tie all packages in the cluster together.

So no, lets keep system: true.

Overwritable?

This I have not yet analysed properly, as I do not see yet a concrete use case, so let's park this part of proposal for now, and only analyse it when we have concrete use cases. We have created things that are too complicated already, adding complexity on top I would prefer to avoid.

[Heulitig]

Proposal: Auto-importing system package using system: <alias>

;; FASTN.ftd
-- fastn.package: design-system 
system: ds
system-is-confidential: false

So for referring the current package in it, we should auto-import the current system package by using the value provided by system header as alias system: <alias>.

In case someone wants to refer to the current system package like this.

;; index.ftd

-- ds.page:

<definition omitted>

-- end: ds.page