Skip to content

Commit f05f421

Browse files
lovasoalovasoa
committed
add docs
1 parent a59233e commit f05f421

File tree

5 files changed

+153
-0
lines changed

5 files changed

+153
-0
lines changed

‎examples/official-site/highlightjs-tabler-theme.css

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,3 +105,11 @@ code .hljs-punctuation::selection {
105105
pre code {
106106
padding: 0;
107107
}
108+
109+
/* Limit height and add inset shadow to code blocks */
110+
pre:has(code) {
111+
max-height: 33vh; /* Limit height */
112+
overflow: auto;
113+
box-shadow: inset -10px -10px 30px #000000af; /* Inset shadow */
114+
border-radius: .5rem;
115+
}

‎src/lib.rs

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,73 @@
11
#![deny(clippy::pedantic)]
22
#![allow(clippy::missing_errors_doc, clippy::missing_panics_doc)]
33

4+
//! [SQLPage](https://sql-page.com) is a high-performance web server that converts SQL queries
5+
//! into dynamic web applications by rendering [handlebars templates](https://sql-page.com/custom_components.sql)
6+
//! with data coming from SQL queries declared in `.sql` files.
7+
//!
8+
//! # Overview
9+
//!
10+
//! SQLPage is a web server that lets you build data-centric applications using only SQL queries.
11+
//! It automatically converts database queries into professional-looking web pages using pre-built components
12+
//! for common UI patterns like [tables](https://sql-page.com/component.sql?component=table),
13+
//! [charts](https://sql-page.com/component.sql?component=chart),
14+
//! [forms](https://sql-page.com/component.sql?component=form), and more.
15+
//!
16+
//! # Key Features
17+
//!
18+
//! - **SQL-Only Development**: Build full web applications without HTML, CSS, or JavaScript
19+
//! - **Built-in Components**: Rich library of [pre-made UI components](https://sql-page.com/documentation.sql)
20+
//! - **Security**: Protection against [SQL injection, XSS and other vulnerabilities](https://sql-page.com/safety.sql)
21+
//! - **Performance**: [Optimized request handling and rendering](https://sql-page.com/performance.sql)
22+
//! - **Database Support**: Works with SQLite, PostgreSQL, MySQL, and MS SQL Server
23+
//!
24+
//! # Architecture
25+
//!
26+
//! The crate is organized into several key modules:
27+
//!
28+
//! - [`webserver`]: Core HTTP server implementation using actix-web
29+
//! - [`render`]: Component rendering system, streaming rendering of the handlebars templates with data
30+
//! - [`templates`]: Pre-defined UI component definitions
31+
//! - [`file_cache`]: Caching layer for SQL file parsing
32+
//! - [`filesystem`]: Abstract interface for disk and DB-stored files
33+
//! - [`app_config`]: Configuration and environment handling
34+
//!
35+
//! # Query Processing Pipeline
36+
//!
37+
//! When processing a request, SQLPage:
38+
//!
39+
//! 1. Parses the SQL using sqlparser-rs. Once a SQL file is parsed, it is cached for later reuse.
40+
//! 2. Executes queries through sqlx.
41+
//! 3. Finds the requested component's handlebars template in the database or in the filesystem.
42+
//! 4. Maps results to the component template, using handlebars-rs.
43+
//! 5. Streams rendered HTML to the client.
44+
//!
45+
//! # Extended Functionality
46+
//!
47+
//! - [Custom SQL Functions](https://sql-page.com/functions.sql)
48+
//! - [Custom Components](https://sql-page.com/custom_components.sql)
49+
//! - [Authentication & Sessions](https://sql-page.com/examples/authentication)
50+
//! - [File Uploads](https://sql-page.com/examples/handle_picture_upload.sql)
51+
//!
52+
//! # Example
53+
//!
54+
//! ```sql
55+
//! -- Open a data list component
56+
//! SELECT 'list' as component, 'Users' as title;
57+
//!
58+
//! -- Populate it with data
59+
//! SELECT
60+
//! name as title,
61+
//! email as description
62+
//! FROM users
63+
//! ORDER BY created_at DESC;
64+
//! ```
65+
//!
66+
//! For more examples and documentation, visit:
67+
//! - [Getting Started Guide](https://sql-page.com/get%20started.sql)
68+
//! - [Component Reference](https://sql-page.com/components.sql)
69+
//! - [Example Gallery](https://sql-page.com/examples/tabs)
70+
471
extern crate core;
572

673
pub mod app_config;

‎src/render.rs

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,46 @@
1+
//! Handles the rendering of SQL query results into HTTP responses using components.
2+
//!
3+
//! This module is responsible for transforming database query results into formatted HTTP responses
4+
//! by utilizing a component-based rendering system. It supports multiple output formats including HTML,
5+
//! JSON, and CSV.
6+
//!
7+
//! # Components
8+
//!
9+
//! Components are small user interface elements that display data in specific ways. The rendering
10+
//! system supports two types of parameters for components:
11+
//!
12+
//! * **Top-level parameters**: Properties that customize the component's appearance and behavior
13+
//! * **Row-level parameters**: The actual data to be displayed within the component
14+
//!
15+
//! # Page Context States
16+
//!
17+
//! The rendering process moves through different states represented by [`PageContext`]:
18+
//!
19+
//! * `Header`: Initial state for processing HTTP headers and response setup
20+
//! * `Body`: Active rendering state where component output is generated
21+
//! * `Close`: Final state indicating the response is complete
22+
//!
23+
//! # Header Components
24+
//!
25+
//! Some components must be processed before any response body is sent:
26+
//!
27+
//! * [`status_code`](https://sql-page.com/component.sql?component=status_code): Sets the HTTP response status
28+
//! * [`http_header`](https://sql-page.com/component.sql?component=http_header): Sets custom HTTP headers
29+
//! * [`redirect`](https://sql-page.com/component.sql?component=redirect): Performs HTTP redirects
30+
//! * `authentication`: Handles password-protected access
31+
//! * `cookie`: Manages browser cookies
32+
//!
33+
//! # Body Components
34+
//!
35+
//! The module supports multiple output formats through different renderers:
36+
//!
37+
//! * HTML: Renders templated HTML output using components
38+
//! * JSON: Generates JSON responses for API endpoints
39+
//! * CSV: Creates downloadable CSV files
40+
//!
41+
//! For more details on available components and their usage, see the
42+
//! [SQLPage documentation](https://sql-page.com/documentation.sql).
43+
144
use crate::templates::SplitTemplate;
245
use crate::webserver::http::RequestContext;
346
use crate::webserver::response_writer::{AsyncResponseWriter, ResponseWriter};

‎src/webserver/http.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
//! This module handles HTTP requests and responses for the web server,
2+
//! including rendering SQL files, serving static content, and managing
3+
//! request contexts and response headers.
4+
15
use crate::render::{AnyRenderBodyContext, HeaderContext, PageContext};
26
use crate::webserver::content_security_policy::ContentSecurityPolicy;
37
use crate::webserver::database::execute_queries::stop_at_first_error;

‎src/webserver/mod.rs

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,34 @@
1+
//! Core HTTP server implementation handling SQL file execution and request processing.
2+
//!
3+
//! For more general information about perfomance in sqlite, read our
4+
//! [performance guide](https://sql-page.com/performance.sql).
5+
//!
6+
//! # Overview
7+
//!
8+
//! The webserver module is responsible for:
9+
//! - Processing incoming HTTP requests
10+
//! - Executing SQL files
11+
//! - Streaming query results to clients
12+
//! - Managing database connections
13+
//! - Handling file uploads and static content
14+
//!
15+
//! # Architecture
16+
//!
17+
//! Key components:
18+
//!
19+
//! - [`database`]: SQL execution engine and query processing
20+
//! - [`database::execute_queries`]: Streams query results from database
21+
//! - [`database::migrations`]: Database schema management
22+
//!
23+
//! - [`http`]: HTTP server implementation using actix-web
24+
//! - Request handling
25+
//! - Response streaming
26+
//! - [Content Security Policy](https://sql-page.com/safety.sql) enforcement
27+
//!
28+
//! - [`response_writer`]: Streaming response generation
29+
//! - [`static_content`]: Static asset handling (JS, CSS, icons)
30+
//!
31+
132
mod content_security_policy;
233
pub mod database;
334
pub mod error_with_status;

0 commit comments

Comments
 (0)