From dfff9b30efc82d7507fbfa595b46997e1946eab3 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Tue, 7 Nov 2023 17:27:54 +0530 Subject: [PATCH 1/7] WIP rfc: unified-configuration --- rfcs/0000-unified-configuration.ftd | 188 ++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 rfcs/0000-unified-configuration.ftd diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd new file mode 100644 index 000000000..511c81cf6 --- /dev/null +++ b/rfcs/0000-unified-configuration.ftd @@ -0,0 +1,188 @@ +-- import: fastn.com/rfcs/lib +-- import: fastn-community.github.io/bling/note + +-- lib.rfc: RFC: Unified Configuration +id: unified-config +status: proposal + +TODO: Write a brief summary of the RFC here. + + +-- lib.motivation: + +;; TODO: add links to the following paragraph +Currently, `fastn` supports configuration through environment variables, and in +some way, through the `FASTN.ftd` file. Environment variables are good to +change the behaviour of the cli or to pass secret information but it's not +ideal for defining complex configuration for a framework like `fastn` that +provides various configurable features like processors, oauth authentication +and, apps. + +;; TODO: I can do better than this +This RFC proposes a way of dealing with configuration that is centralised and +leveraged the existing ability of the `fastn` cli to read environment +variables. + +-- end: lib.motivation + + +-- lib.detailed-design: + +-- ds.h2: `fastn/config` - A virtual module to assist configuration definition. + +Add a virtual module (`fastn/config`) similar to existing [assets](TODO: add +link) module. + +;; TODO add footer section for explanors like foreign variables and virtual module +- This module contains all special configuration types defined by the fastn + framework. This module also provides safe access to environment variables + through foreign variables. + +- `FASTN.ftd` file will be central to the whole configuration system. Users can + modify the behaviour of a dependency by passing variables when they're added. + Example: + +-- ds.code: +lang: ftd + +;; FASTN.ftd of test-todos +\-- import: fastn + +\-- fastn.package: test-todos + +\;; fastn.app works in similar way +\-- fastn.dependency: amitu.com/todos +max-todo-per-page: 30 +ignore-value: test \;; amitu.com/todos doesn't have this variable so we ignore this + +-- end: ds.code + + +-- ds.markdown: + +The above snippet is configuring `amitu.com/todos` by modifying variables that +are in its `FASTN.ftd` file. + +The `FASTN.ftd` of `amitu.com/todos` will look like this: + +-- ds.code: +lang: ftd + +;; FASTN.ftd of amitu.com/todos +\-- import: fastn + +\-- fastn.package: amitu.com/todos + +\-- integer max-todo-per-page: 10 \;; becomes 30 when used by test-todos + +\-- string sample-title: TODO App \;; this was not modified by test-todos so this stays intact + +-- end: ds.code + + +-- ds.markdown: + +- While adding dependency, users can modify any variable defined in the + `FASTN.ftd` file of the said dependency. Any variable that is not defined + there is simply ignored + +- Variables defined in `FASTN.ftd` are also considered by the framework + features. Example: Github OAuth feature (this is a processor) can specify + that it needs `gh-oauth` variable of type `github` defined in user's + `FASTN.ftd` file for it to work in user's `FASTN.ftd` file for it to work + (the error handling when `gh-oauth` is not available depends on the + implementation). + +- Variables created using types from `fastn/congi` (as well as primitive types) + are normal variables that can be defined in any `.ftd` file. + +- Only the variables defined in `FASTN.ftd` will be available for access from + `fastn/config` module. See this example to see how one would use a config + variable creatd elsewhere ;; TODO: add example + +Q. Why do we allow defining config variables outside of `FASTN.ftd`? + + + +Configurations are meant to modify the behaviour of the framework or an +external fastn package. Even though this change in behaviour or modification in +configuration of a package should happen in `FASTN.ftd` file, we should give +users option to define configuration that are scoped for a single use. + +Consider the following example that uses the [pg processor](): + +-- ds.code: +lang: ftd + +\;; sample.ftd +\-- import: fastn/processors as pr +\-- import: fastn/config + +\-- config.db-conn temp: +db_host: +db_user: user +db_password: config.DB_PASSWORD ;; this is an environment variable +db_name: user_db + +\-- person list people: +$processor$: pr.pg +use: $temp + +SELECT * FROM users; + + +-- note.note: + +If the use of pg processor doesn't specify database connections information +through the `use` header, the implementation of `pg` can choose to look for a +default variable (say `db`) in `FASTN.ftd`. Looking into arbitray `.ftd` file +is not supported. Any rust implementation will only be able to access variables +defined in `FASTN.ftd` for configuration stuff. + + +-- ds.markdown: + +In summary, a processor like `pg` would say: "Pass connection information +through the `use` header or it'll pick `db` variable of type `config.db-conn` +from your `FASTN.ftd` file. + + + + +-- ds.h2: TODO + +- Write implementation details. + + +-- end: lib.detailed-design + + +-- lib.alternatives: + +Did you consider any alternatives to what you propose in detailed-design, if so +mention them here, along with discussion on why you consider the proposal better. + +-- end: lib.alternatives + + + + +-- lib.teaching-notes: + +How hard would it be to teach this feature? + +-- end: lib.teaching-notes + + + +-- lib.unresolved-questions: + +List unresolved questions here. + +-- end: lib.unresolved-questions + + + +-- end: lib.rfc + + From 1409668a8fd8fe62288b91528d6c9d90028e0006 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Tue, 7 Nov 2023 20:09:31 +0530 Subject: [PATCH 2/7] correct use of ds.code and note add caption to code blocks and headings to note --- rfcs/0000-unified-configuration.ftd | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd index 511c81cf6..3e37fff33 100644 --- a/rfcs/0000-unified-configuration.ftd +++ b/rfcs/0000-unified-configuration.ftd @@ -42,10 +42,9 @@ link) module. modify the behaviour of a dependency by passing variables when they're added. Example: --- ds.code: +-- ds.code: `FASTN.ftd` of test-todos lang: ftd -;; FASTN.ftd of test-todos \-- import: fastn \-- fastn.package: test-todos @@ -65,10 +64,9 @@ are in its `FASTN.ftd` file. The `FASTN.ftd` of `amitu.com/todos` will look like this: --- ds.code: +-- ds.code: FASTN.ftd of amitu.com/todos lang: ftd -;; FASTN.ftd of amitu.com/todos \-- import: fastn \-- fastn.package: amitu.com/todos @@ -111,10 +109,9 @@ users option to define configuration that are scoped for a single use. Consider the following example that uses the [pg processor](): --- ds.code: +-- ds.code: `sample.ftd` lang: ftd -\;; sample.ftd \-- import: fastn/processors as pr \-- import: fastn/config @@ -131,7 +128,7 @@ use: $temp SELECT * FROM users; --- note.note: +-- note.note: Sidenote If the use of pg processor doesn't specify database connections information through the `use` header, the implementation of `pg` can choose to look for a From 5fcd2fd435f4479915c450606a4c78f19e9e4a61 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Tue, 7 Nov 2023 20:17:37 +0530 Subject: [PATCH 3/7] mention cli args as a way to configure + fix typos --- rfcs/0000-unified-configuration.ftd | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd index 3e37fff33..5921c7235 100644 --- a/rfcs/0000-unified-configuration.ftd +++ b/rfcs/0000-unified-configuration.ftd @@ -11,12 +11,12 @@ TODO: Write a brief summary of the RFC here. -- lib.motivation: ;; TODO: add links to the following paragraph -Currently, `fastn` supports configuration through environment variables, and in -some way, through the `FASTN.ftd` file. Environment variables are good to -change the behaviour of the cli or to pass secret information but it's not -ideal for defining complex configuration for a framework like `fastn` that -provides various configurable features like processors, oauth authentication -and, apps. +Currently, `fastn` supports configuration through environment variables, cli +arguments, and in some way, through the `FASTN.ftd` file. Environment variables +are good to change the behaviour of the cli or to pass secret information but +it's not ideal for defining complex configuration for a framework like `fastn` +which provides various configurable features like processors, oauth +authentication and, apps. ;; TODO: I can do better than this This RFC proposes a way of dealing with configuration that is centralised and @@ -82,8 +82,9 @@ lang: ftd - While adding dependency, users can modify any variable defined in the `FASTN.ftd` file of the said dependency. Any variable that is not defined - there is simply ignored + there is simply ignored. +;; TODO: rephrase this! ambiguous statement - Variables defined in `FASTN.ftd` are also considered by the framework features. Example: Github OAuth feature (this is a processor) can specify that it needs `gh-oauth` variable of type `github` defined in user's @@ -91,12 +92,15 @@ lang: ftd (the error handling when `gh-oauth` is not available depends on the implementation). -- Variables created using types from `fastn/congi` (as well as primitive types) +- Variables created using types from `fastn/config` (as well as primitive types) are normal variables that can be defined in any `.ftd` file. +;; TODO: rephrase this: what I mean is that variables in `*.ftd` will not be +;; considered, only `FASTN.ftd` will be considered when accessing variables using +;; `fastn/config` - Only the variables defined in `FASTN.ftd` will be available for access from `fastn/config` module. See this example to see how one would use a config - variable creatd elsewhere ;; TODO: add example + variable created elsewhere ;; TODO: add example Q. Why do we allow defining config variables outside of `FASTN.ftd`? From b4780c9d01ec0667beffdfe066ad7f7b8c8535cc Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Thu, 9 Nov 2023 17:40:19 +0530 Subject: [PATCH 4/7] add configuring of deps + other sections --- rfcs/0000-unified-configuration.ftd | 245 +++++++++++++++++++++------- 1 file changed, 184 insertions(+), 61 deletions(-) diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd index 5921c7235..dffe958d1 100644 --- a/rfcs/0000-unified-configuration.ftd +++ b/rfcs/0000-unified-configuration.ftd @@ -5,22 +5,24 @@ id: unified-config status: proposal -TODO: Write a brief summary of the RFC here. +A configuration system streamlining complex settings for processors, fastn +packages. It introduces: +- Special Configuration types in the `fastn` namespace. +- A virtual module for configuration access in userland. +- Package level configuration. -- lib.motivation: -;; TODO: add links to the following paragraph -Currently, `fastn` supports configuration through environment variables, cli -arguments, and in some way, through the `FASTN.ftd` file. Environment variables -are good to change the behaviour of the cli or to pass secret information but -it's not ideal for defining complex configuration for a framework like `fastn` -which provides various configurable features like processors, oauth -authentication and, apps. - -;; TODO: I can do better than this -This RFC proposes a way of dealing with configuration that is centralised and -leveraged the existing ability of the `fastn` cli to read environment +Currently, `fastn` supports configuration through [environment +variables](/env/), cli arguments, and in some way, through the `FASTN.ftd` +file. Environment variables are good to change the behaviour of the cli or to +pass secret information but it's not ideal for defining complex configuration +for a framework like `fastn` which provides various configurable features like +[processors](/processor/-/backend/), oauth authentication and, apps. + +This RFC proposes a way of dealing with configuration that is centralized and +leverages the existing ability of the `fastn` cli to read environment variables. -- end: lib.motivation @@ -28,19 +30,103 @@ variables. -- lib.detailed-design: --- ds.h2: `fastn/config` - A virtual module to assist configuration definition. +-- ds.h2: Configuration types in `fastn.*` + +This contains all special configuration types defined by the fastn framework. + +Any configuration required by the framework will be present as a type under the +`fastn` namespace. + +For example, `db-conn` that represents database connection information is a type +under `fastn` which can be used to create variables like: + +-- ds.code: variable in `FASTN.ftd` of `my-package` +lang: ftd + +\-- import: fastn + +\-- fastn.package: my-package + +\-- fastn.db-conn my-db: +db_host: +db_user: user +db_password: config.DB_PASSWORD ;; this is an environment variable +db_name: user_db + +-- ds.markdown: + +A corresponding struct for `db-conn` on rust side would look like: + +-- ds.code: `db-conn` in rust +lang: rust + +struct DatabaseConnInfo { + db_host: String, + db_user: String, + db_password: String, + db_name: String, +} + +-- ds.markdown: + +The `fastn` namespace will also allow access to environment variables using +`fast.env` function. + +-- ds.code: A variable that reads environment variable using `fastn.env()` +lang: ftd + +\-- import: fastn + +\-- fastn.package: my-package + +\-- fastn.db-conn my-db: +db_host: +db_user: user +db_password: fastn.env(DB_PASSWORD) \;; suggested syntax +db_name: user_db + +-- note.note: `fastn.env()` + +It is a foreign function. A default value can be provided in case `DB_PASSWORD` doesn't exist: `fastn.env(DB_PASSWORD, default=admin)`. + +-- ds.markdown: + +- Some special variable names may be defined in `FASTN.ftd` file that are + required by the framework. Example: The implementation of [`pg` + processor](/sql/) may require the user of this processor to define a variable + name `db` in their package's `FASTN.ftd` file. + +- Variables created using types from `fastn.*` (as well as primitive types) + are normal variables that can be defined in any `.ftd` file. + +The virtual module (`/-/config`) will handle access of variables +defined in `FASTN.ftd`. + +-- ds.h2: `/-/config` - A virtual module to assist configuration access. + +Add a virtual module (`/-/config`) similar to existing +[assets](https://fastn.com/assets) module. + +This module will allow access to variables defined in `FASTN.ftd` file. + +-- ds.code: Example +lang: ftd + +\-- import: my-package/-/config \;; This is new! + +\-- import: fastn/processors as pr + +\-- person list people: +$processor$: pr.pg +use: $config.my-db \;; defined in my-package's FASTN.ftd -Add a virtual module (`fastn/config`) similar to existing [assets](TODO: add -link) module. +SELECT * FROM users; -;; TODO add footer section for explanors like foreign variables and virtual module -- This module contains all special configuration types defined by the fastn - framework. This module also provides safe access to environment variables - through foreign variables. +-- ds.h2: Configuring dependencies and apps -- `FASTN.ftd` file will be central to the whole configuration system. Users can - modify the behaviour of a dependency by passing variables when they're added. - Example: +`FASTN.ftd` file will be central to the whole configuration system. Users can +modify the behaviour of a dependency by passing variables when they're added. +Example: -- ds.code: `FASTN.ftd` of test-todos lang: ftd @@ -52,11 +138,9 @@ lang: ftd \;; fastn.app works in similar way \-- fastn.dependency: amitu.com/todos max-todo-per-page: 30 -ignore-value: test \;; amitu.com/todos doesn't have this variable so we ignore this -- end: ds.code - -- ds.markdown: The above snippet is configuring `amitu.com/todos` by modifying variables that @@ -77,32 +161,53 @@ lang: ftd -- end: ds.code - -- ds.markdown: - While adding dependency, users can modify any variable defined in the - `FASTN.ftd` file of the said dependency. Any variable that is not defined - there is simply ignored. - -;; TODO: rephrase this! ambiguous statement -- Variables defined in `FASTN.ftd` are also considered by the framework - features. Example: Github OAuth feature (this is a processor) can specify - that it needs `gh-oauth` variable of type `github` defined in user's - `FASTN.ftd` file for it to work in user's `FASTN.ftd` file for it to work - (the error handling when `gh-oauth` is not available depends on the - implementation). - -- Variables created using types from `fastn/config` (as well as primitive types) - are normal variables that can be defined in any `.ftd` file. + `FASTN.ftd` file of the said dependency. + +- Any extra header value passed to `fastn.dependency` will result in an error. + +-- ds.h2: Optional vs. Required dependency configuration + +A package can create variables in `FASTN.ftd` in different ways which will +dictate if they're required or optional. See the example below: + +-- ds.code: `FASTN.ftd` of `amitu.com/todos` +lang: ftd -;; TODO: rephrase this: what I mean is that variables in `*.ftd` will not be -;; considered, only `FASTN.ftd` will be considered when accessing variables using -;; `fastn/config` -- Only the variables defined in `FASTN.ftd` will be available for access from - `fastn/config` module. See this example to see how one would use a config - variable created elsewhere ;; TODO: add example +\-- import: fastn + +\-- fastn.package: amitu.com/todos +db: $my-db-for-dev \;; this value for db is available only when it's not used as a dependency + +\-- fastn.db-conn db: \;; this has no value so this will be required + +\-- integer max-todos: 30 \;; this has a default value so this is optional + +-- ds.markdown: + +- `db` must be defined when the package is being used, and fastn.package is one + such usage! This allows for easy testing, say if I am building + amitu.com/todos, I do not have to create a test app, and I can work directly + in amitu.com/todos package, and my test values would be passed there. + +- `max-todos` is defined with a value so this doesn't have to be passed as a + header when using `amitu.com/todos` as a dependency. -Q. Why do we allow defining config variables outside of `FASTN.ftd`? +-- ds.code: Example use of `amitu.com/todos` in `my-website` +lang: ftd + +\-- import: fastn + +\-- fastn.package: my-website + +\-- fastn.dependency: amitu.com/todos +db: $my-db \;; this is required otherwise an error will be thrown +\;; max-todos is optional so we ignore this + + +-- ds.h3: Q. Why do we allow defining config variables outside of `FASTN.ftd`? @@ -111,7 +216,7 @@ external fastn package. Even though this change in behaviour or modification in configuration of a package should happen in `FASTN.ftd` file, we should give users option to define configuration that are scoped for a single use. -Consider the following example that uses the [pg processor](): +Consider the following example that uses the [`pg` processor](/sql/): -- ds.code: `sample.ftd` lang: ftd @@ -132,11 +237,11 @@ use: $temp SELECT * FROM users; --- note.note: Sidenote +-- note.note: Side note If the use of pg processor doesn't specify database connections information through the `use` header, the implementation of `pg` can choose to look for a -default variable (say `db`) in `FASTN.ftd`. Looking into arbitray `.ftd` file +default variable (say `db`) in `FASTN.ftd`. Looking into arbitrary `.ftd` file is not supported. Any rust implementation will only be able to access variables defined in `FASTN.ftd` for configuration stuff. @@ -150,40 +255,58 @@ from your `FASTN.ftd` file. --- ds.h2: TODO - -- Write implementation details. - - -- end: lib.detailed-design -- lib.alternatives: -Did you consider any alternatives to what you propose in detailed-design, if so -mention them here, along with discussion on why you consider the proposal better. +Another way is to stick with how fastn currently reads environment variables. +It's good because it keeps secret info safe in source files. But there are some +downsides: --- end: lib.alternatives +- We still need a way to share settings between packages (like dependencies and + apps). +- People don't have a straightforward system to make their packages adjustable + by the outside world. +-- end: lib.alternatives -- lib.teaching-notes: -How hard would it be to teach this feature? +- At a minimum, framework features might require users to define a variable + in their FASTN.ftd file, and this process is quite straightforward to + explain. --- end: lib.teaching-notes +- Likewise, when incorporating dependencies into FASTN.ftd, it's preferable for + the documentation of the dependency to document all potential configurations. +- Power users and library authors can choose to dive deep in the docs and + explore how they can use the `/-/config` virtual module to access + variables defined in their package's `FASTN.ftd`. +-- end: lib.teaching-notes -- lib.unresolved-questions: -List unresolved questions here. +This RFC doesn't address the security concerns around this feature. Some points to consider here: --- end: lib.unresolved-questions +- Environment variables accessed using `fastn.env()` could be leaked in client code. Example: + +-- ds.code: Client can print environment variables +lang: ftd +\-- import: fastn +\-- ftd.text: $fastn.env(DB_PASSWORD) ;; this is bad --- end: lib.rfc +-- ds.markdown: +- We need some way to limit access of environment variables. + + +-- end: lib.unresolved-questions + +-- end: lib.rfc From 80d924eecff00bea212d4eceaa98ec05952c8f0d Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Thu, 9 Nov 2023 17:50:29 +0530 Subject: [PATCH 5/7] use kebab-case in ftd --- rfcs/0000-unified-configuration.ftd | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd index dffe958d1..c5b42b1b6 100644 --- a/rfcs/0000-unified-configuration.ftd +++ b/rfcs/0000-unified-configuration.ftd @@ -48,10 +48,10 @@ lang: ftd \-- fastn.package: my-package \-- fastn.db-conn my-db: -db_host: -db_user: user -db_password: config.DB_PASSWORD ;; this is an environment variable -db_name: user_db +db-host: +db-user: user +db-password: config.DB_PASSWORD ;; this is an environment variable +db-name: user_db -- ds.markdown: @@ -80,10 +80,10 @@ lang: ftd \-- fastn.package: my-package \-- fastn.db-conn my-db: -db_host: -db_user: user -db_password: fastn.env(DB_PASSWORD) \;; suggested syntax -db_name: user_db +db-host: +db-user: user +db-password: fastn.env(DB_PASSWORD) \;; suggested syntax +db-name: user_db -- note.note: `fastn.env()` From fa79f7cfa3f4b85ca3e3b43742ce404b855c366a Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Thu, 9 Nov 2023 18:09:23 +0530 Subject: [PATCH 6/7] remove special config types and impose restriction Only FASTN.ftd is allowed to have config variables for now. `fastn.env()` is allowed in FASTN.ftd only --- rfcs/0000-unified-configuration.ftd | 110 ++-------------------------- 1 file changed, 8 insertions(+), 102 deletions(-) diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd index c5b42b1b6..f62072b18 100644 --- a/rfcs/0000-unified-configuration.ftd +++ b/rfcs/0000-unified-configuration.ftd @@ -8,7 +8,7 @@ status: proposal A configuration system streamlining complex settings for processors, fastn packages. It introduces: -- Special Configuration types in the `fastn` namespace. +- Access to environment variables in `FASTN.ftd` - A virtual module for configuration access in userland. - Package level configuration. @@ -27,50 +27,12 @@ variables. -- end: lib.motivation - -- lib.detailed-design: --- ds.h2: Configuration types in `fastn.*` - -This contains all special configuration types defined by the fastn framework. - -Any configuration required by the framework will be present as a type under the -`fastn` namespace. - -For example, `db-conn` that represents database connection information is a type -under `fastn` which can be used to create variables like: - --- ds.code: variable in `FASTN.ftd` of `my-package` -lang: ftd - -\-- import: fastn - -\-- fastn.package: my-package - -\-- fastn.db-conn my-db: -db-host: -db-user: user -db-password: config.DB_PASSWORD ;; this is an environment variable -db-name: user_db +-- ds.h2: Access to environment variables --- ds.markdown: - -A corresponding struct for `db-conn` on rust side would look like: - --- ds.code: `db-conn` in rust -lang: rust - -struct DatabaseConnInfo { - db_host: String, - db_user: String, - db_password: String, - db_name: String, -} - --- ds.markdown: - -The `fastn` namespace will also allow access to environment variables using -`fast.env` function. +The `fastn` namespace will have a function, `fastn.env()` to access environment +variables. -- ds.code: A variable that reads environment variable using `fastn.env()` lang: ftd @@ -79,15 +41,11 @@ lang: ftd \-- fastn.package: my-package -\-- fastn.db-conn my-db: -db-host: -db-user: user -db-password: fastn.env(DB_PASSWORD) \;; suggested syntax -db-name: user_db +\-- string my-db-url: $fastn.env(DB_URL) -- note.note: `fastn.env()` -It is a foreign function. A default value can be provided in case `DB_PASSWORD` doesn't exist: `fastn.env(DB_PASSWORD, default=admin)`. +It is a foreign function. A default value can be provided in case `DB_URL` doesn't exist: `fastn.env(DB_URL, default=postgres://0:5432/maindb)`. -- ds.markdown: @@ -96,9 +54,6 @@ It is a foreign function. A default value can be provided in case `DB_PASSWORD` processor](/sql/) may require the user of this processor to define a variable name `db` in their package's `FASTN.ftd` file. -- Variables created using types from `fastn.*` (as well as primitive types) - are normal variables that can be defined in any `.ftd` file. - The virtual module (`/-/config`) will handle access of variables defined in `FASTN.ftd`. @@ -118,7 +73,7 @@ lang: ftd \-- person list people: $processor$: pr.pg -use: $config.my-db \;; defined in my-package's FASTN.ftd +use: $config.my-db-url \;; defined in my-package's FASTN.ftd SELECT * FROM users; @@ -181,7 +136,7 @@ lang: ftd \-- fastn.package: amitu.com/todos db: $my-db-for-dev \;; this value for db is available only when it's not used as a dependency -\-- fastn.db-conn db: \;; this has no value so this will be required +\-- string db: \;; this has no value so this will be required \-- integer max-todos: 30 \;; this has a default value so this is optional @@ -206,55 +161,6 @@ lang: ftd db: $my-db \;; this is required otherwise an error will be thrown \;; max-todos is optional so we ignore this - --- ds.h3: Q. Why do we allow defining config variables outside of `FASTN.ftd`? - - - -Configurations are meant to modify the behaviour of the framework or an -external fastn package. Even though this change in behaviour or modification in -configuration of a package should happen in `FASTN.ftd` file, we should give -users option to define configuration that are scoped for a single use. - -Consider the following example that uses the [`pg` processor](/sql/): - --- ds.code: `sample.ftd` -lang: ftd - -\-- import: fastn/processors as pr -\-- import: fastn/config - -\-- config.db-conn temp: -db_host: -db_user: user -db_password: config.DB_PASSWORD ;; this is an environment variable -db_name: user_db - -\-- person list people: -$processor$: pr.pg -use: $temp - -SELECT * FROM users; - - --- note.note: Side note - -If the use of pg processor doesn't specify database connections information -through the `use` header, the implementation of `pg` can choose to look for a -default variable (say `db`) in `FASTN.ftd`. Looking into arbitrary `.ftd` file -is not supported. Any rust implementation will only be able to access variables -defined in `FASTN.ftd` for configuration stuff. - - --- ds.markdown: - -In summary, a processor like `pg` would say: "Pass connection information -through the `use` header or it'll pick `db` variable of type `config.db-conn` -from your `FASTN.ftd` file. - - - - -- end: lib.detailed-design From 8d5119db8ed2c4ef8f6dea95282a98984e969531 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Thu, 9 Nov 2023 18:40:13 +0530 Subject: [PATCH 7/7] fix syntax of fastn.env --- rfcs/0000-unified-configuration.ftd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfcs/0000-unified-configuration.ftd b/rfcs/0000-unified-configuration.ftd index f62072b18..bd3af7b5b 100644 --- a/rfcs/0000-unified-configuration.ftd +++ b/rfcs/0000-unified-configuration.ftd @@ -41,11 +41,11 @@ lang: ftd \-- fastn.package: my-package -\-- string my-db-url: $fastn.env(DB_URL) +\-- string my-db-url: $fastn.env(name = DB_URL) -- note.note: `fastn.env()` -It is a foreign function. A default value can be provided in case `DB_URL` doesn't exist: `fastn.env(DB_URL, default=postgres://0:5432/maindb)`. +It is a foreign function. A default value can be provided in case `DB_URL` doesn't exist: `fastn.env(name = DB_URL, default = postgres://0:5432/maindb)`. -- ds.markdown: @@ -205,7 +205,7 @@ lang: ftd \-- import: fastn -\-- ftd.text: $fastn.env(DB_PASSWORD) ;; this is bad +\-- ftd.text: $fastn.env(name = DB_PASSWORD) ;; this is bad -- ds.markdown: