LCORE-973: CORS configuration

docs/config.html

@@ -172,20 +172,8 @@
 <h1 class="title"> </h1>
 </header>
 <h1 id="lightspeed-core-stack">Lightspeed Core Stack</h1>
-<h2 id="base-url">🌍 Base URL</h2>
-<table>
-<thead>
-<tr class="header">
-<th>URL</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-</tbody>
-</table>
-<h1 id="apis">🛠️ APIs</h1>
 <hr />
-<h1 id="components">📋 Components</h1>
+<h1 id="configuration-schema">📋 Configuration schema</h1>
 <h2 id="accessrule">AccessRule</h2>
 <p>Rule defining what actions a role can perform.</p>
 <table>
@@ -317,7 +305,27 @@ <h2 id="byokrag">ByokRag</h2>
 </table>
 <h2 id="corsconfiguration">CORSConfiguration</h2>
 <p>CORS configuration.</p>
+<p>CORS or ‘Cross-Origin Resource Sharing’ refers to the situations when
+a frontend running in a browser has JavaScript code that communicates
+with a backend, and the backend is in a different ‘origin’ than the
+frontend.</p>
+<p>Useful resources:</p>
+<ul>
+<li><a href="https://fastapi.tiangolo.com/tutorial/cors/">CORS in
+FastAPI</a></li>
+<li><a
+href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Wikipedia
+article</a></li>
+<li><a
+href="https://dev.to/akshay_chauhan/what-is-cors-explained-8f1">What is
+CORS?</a></li>
+</ul>
 <table>
+<colgroup>
+<col style="width: 26%" />
+<col style="width: 23%" />
+<col style="width: 50%" />
+</colgroup>
 <thead>
 <tr class="header">
 <th>Field</th>
@@ -329,22 +337,30 @@ <h2 id="corsconfiguration">CORSConfiguration</h2>
 <tr class="odd">
 <td>allow_origins</td>
 <td>array</td>
-<td></td>
+<td>A list of origins allowed for cross-origin requests. An origin is
+the combination of protocol (http, https), domain (myapp.com, localhost,
+localhost.tiangolo.com), and port (80, 443, 8080). Use [’*’] to allow
+all origins.</td>
 </tr>
 <tr class="even">
 <td>allow_credentials</td>
 <td>boolean</td>
-<td></td>
+<td>Indicate that cookies should be supported for cross-origin
+requests</td>
 </tr>
 <tr class="odd">
 <td>allow_methods</td>
 <td>array</td>
-<td></td>
+<td>A list of HTTP methods that should be allowed for cross-origin
+requests. You can use [’*’] to allow all standard methods.</td>
 </tr>
 <tr class="even">
 <td>allow_headers</td>
 <td>array</td>
-<td></td>
+<td>A list of HTTP request headers that should be supported for
+cross-origin requests. You can use [’*’] to allow all headers. The
+Accept, Accept-Language, Content-Language and Content-Type headers are
+always allowed for simple CORS requests.</td>
 </tr>
 </tbody>
 </table>
@@ -981,8 +997,22 @@ <h2 id="serviceconfiguration">ServiceConfiguration</h2>
 </table>
 <h2 id="tlsconfiguration">TLSConfiguration</h2>
 <p>TLS configuration.</p>
-<p>See also: - https://fastapi.tiangolo.com/deployment/https/ -
-https://en.wikipedia.org/wiki/Transport_Layer_Security</p>
+<p>Transport Layer Security (TLS) is a cryptographic protocol designed
+to provide communications security over a computer network, such as the
+Internet. The protocol is widely used in applications such as email,
+instant messaging, and voice over IP, but its use in securing HTTPS
+remains the most publicly visible.</p>
+<p>Useful resources:</p>
+<ul>
+<li><a href="https://fastapi.tiangolo.com/deployment/https/">FastAPI
+HTTPS Deployment</a></li>
+<li><a
+href="https://en.wikipedia.org/wiki/Transport_Layer_Security">Transport
+Layer Security Overview</a></li>
+<li><a
+href="https://www.ssltrust.eu/learning/ssl/transport-layer-security-tls">What
+is TLS</a></li>
+</ul>
 <table>
 <colgroup>
 <col style="width: 26%" />

docs/config.md

@@ -1,19 +1,9 @@
 # Lightspeed Core Stack
 
 
-
-## 🌍 Base URL
-
-
-| URL | Description |
-|-----|-------------|
-
-
-# 🛠️ APIs
-
 ---
 
-# 📋 Components
+# 📋 Configuration schema
 
 
 
@@ -85,13 +75,23 @@ BYOK RAG configuration.
 
 CORS configuration.
 
+CORS or 'Cross-Origin Resource Sharing' refers to the situations when a
+frontend running in a browser has JavaScript code that communicates with a
+backend, and the backend is in a different 'origin' than the frontend.
+
+Useful resources:
+
+  - [CORS in FastAPI](https://fastapi.tiangolo.com/tutorial/cors/)
+  - [Wikipedia article](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
+  - [What is CORS?](https://dev.to/akshay_chauhan/what-is-cors-explained-8f1)
+
 
 | Field | Type | Description |
 |-------|------|-------------|
-| allow_origins | array |  |
-| allow_credentials | boolean |  |
-| allow_methods | array |  |
-| allow_headers | array |  |
+| allow_origins | array | A list of origins allowed for cross-origin requests. An origin is the combination of protocol (http, https), domain (myapp.com, localhost, localhost.tiangolo.com), and port (80, 443, 8080). Use ['*'] to allow all origins. |
+| allow_credentials | boolean | Indicate that cookies should be supported for cross-origin requests |
+| allow_methods | array | A list of HTTP methods that should be allowed for cross-origin requests. You can use ['*'] to allow all standard methods. |
+| allow_headers | array | A list of HTTP request headers that should be supported for cross-origin requests. You can use ['*'] to allow all headers. The Accept, Accept-Language, Content-Language and Content-Type headers are always allowed for simple CORS requests. |
 
 
 ## Configuration
@@ -373,9 +373,17 @@ Service configuration.
 
 TLS configuration.
 
-See also:
-- https://fastapi.tiangolo.com/deployment/https/
-- https://en.wikipedia.org/wiki/Transport_Layer_Security
+Transport Layer Security (TLS) is a cryptographic protocol designed to
+provide communications security over a computer network, such as the
+Internet. The protocol is widely used in applications such as email,
+instant messaging, and voice over IP, but its use in securing HTTPS remains
+the most publicly visible.
+
+Useful resources:
+
+  - [FastAPI HTTPS Deployment](https://fastapi.tiangolo.com/deployment/https/)
+  - [Transport Layer Security Overview](https://en.wikipedia.org/wiki/Transport_Layer_Security)
+  - [What is TLS](https://www.ssltrust.eu/learning/ssl/transport-layer-security-tls)
 
 
 | Field | Type | Description |

docs/config.puml

@@ -30,10 +30,10 @@ class "ByokRag" as src.models.config.ByokRag {
   vector_db_id : Annotated
 }
 class "CORSConfiguration" as src.models.config.CORSConfiguration {
-  allow_credentials : bool
-  allow_headers : list[str]
-  allow_methods : list[str]
-  allow_origins : list[str]
+  allow_credentials : Optional[bool]
+  allow_headers : Optional[list[str]]
+  allow_methods : Optional[list[str]]
+  allow_origins : Optional[list[str]]
   check_cors_configuration() -> Self
 }
 class "Configuration" as src.models.config.Configuration {

src/models/config.py

@@ -38,9 +38,17 @@ class ConfigurationBase(BaseModel):
 class TLSConfiguration(ConfigurationBase):
     """TLS configuration.
 
-    See also:
-    - https://fastapi.tiangolo.com/deployment/https/
-    - https://en.wikipedia.org/wiki/Transport_Layer_Security
+    Transport Layer Security (TLS) is a cryptographic protocol designed to
+    provide communications security over a computer network, such as the
+    Internet. The protocol is widely used in applications such as email,
+    instant messaging, and voice over IP, but its use in securing HTTPS remains
+    the most publicly visible.
+
+    Useful resources:
+
+      - [FastAPI HTTPS Deployment](https://fastapi.tiangolo.com/deployment/https/)
+      - [Transport Layer Security Overview](https://en.wikipedia.org/wiki/Transport_Layer_Security)
+      - [What is TLS](https://www.ssltrust.eu/learning/ssl/transport-layer-security-tls)
     """
 
     tls_certificate_path: Optional[FilePath] = Field(
@@ -68,14 +76,51 @@ def check_tls_configuration(self) -> Self:
 
 
 class CORSConfiguration(ConfigurationBase):
-    """CORS configuration."""
+    """CORS configuration.
+
+    CORS or 'Cross-Origin Resource Sharing' refers to the situations when a
+    frontend running in a browser has JavaScript code that communicates with a
+    backend, and the backend is in a different 'origin' than the frontend.
+
+    Useful resources:
 
-    allow_origins: list[str] = [
-        "*"
-    ]  # not AnyHttpUrl: we need to support "*" that is not valid URL
-    allow_credentials: bool = False
-    allow_methods: list[str] = ["*"]
-    allow_headers: list[str] = ["*"]
+      - [CORS in FastAPI](https://fastapi.tiangolo.com/tutorial/cors/)
+      - [Wikipedia article](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
+      - [What is CORS?](https://dev.to/akshay_chauhan/what-is-cors-explained-8f1)
+    """
+
+    # not AnyHttpUrl: we need to support "*" that is not valid URL
+    allow_origins: list[str] = Field(
+        ["*"],
+        title="Allow origins",
+        description="A list of origins allowed for cross-origin requests. An origin "
+        "is the combination of protocol (http, https), domain "
+        "(myapp.com, localhost, localhost.tiangolo.com), and port (80, 443, 8080). "
+        "Use ['*'] to allow all origins.",
+    )
+
+    allow_credentials: bool = Field(
+        False,
+        title="Allow credentials",
+        description="Indicate that cookies should be supported for cross-origin requests",
+    )
+
+    allow_methods: list[str] = Field(
+        ["*"],
+        title="Allow methods",
+        description="A list of HTTP methods that should be allowed for "
+        "cross-origin requests. You can use ['*'] to allow "
+        "all standard methods.",
+    )
+
+    allow_headers: list[str] = Field(
+        ["*"],
+        title="Allow headers",
+        description="A list of HTTP request headers that should be supported "
+        "for cross-origin requests. You can use ['*'] to allow all headers. The "
+        "Accept, Accept-Language, Content-Language and Content-Type headers are "
+        "always allowed for simple CORS requests.",
+    )
 
     @model_validator(mode="after")
     def check_cors_configuration(self) -> Self:
@@ -85,8 +130,8 @@ def check_cors_configuration(self) -> Self:
         if self.allow_credentials and "*" in self.allow_origins:
             raise ValueError(
                 "Invalid CORS configuration: allow_credentials can not be set to true when "
-                "allow origins contains '*' wildcard."
-                "Use explicit origins or disable credential."
+                "allow origins contains the '*' wildcard."
+                "Use explicit origins or disable credentials."
             )
         return self
 
@@ -183,7 +228,14 @@ class ServiceConfiguration(ConfigurationBase):
             tls_certificate_path=None, tls_key_path=None, tls_key_password=None
         )
     )
-    cors: CORSConfiguration = Field(default_factory=CORSConfiguration)
+    cors: CORSConfiguration = Field(
+        default_factory=lambda: CORSConfiguration(
+            allow_origins=["*"],
+            allow_credentials=False,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    )
 
     @model_validator(mode="after")
     def check_service_configuration(self) -> Self:

tests/unit/models/config/test_cors.py

@@ -64,8 +64,8 @@ def test_cors_improper_configuration() -> None:
     """Test the CORS configuration."""
     expected = (
         "Value error, Invalid CORS configuration: "
-        + "allow_credentials can not be set to true when allow origins contains '\\*' wildcard."
-        + "Use explicit origins or disable credential."
+        + "allow_credentials can not be set to true when allow origins contains the '\\*' wildcard."
+        + "Use explicit origins or disable credentials."
     )
 
     with pytest.raises(ValueError, match=expected):