diff --git a/.asf.yaml b/.asf.yaml index c6ff7d558325..730f0b352f4e 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -17,7 +17,7 @@ # NOTE: All configurations could be found here: https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features github: - description: "Apache OpenDAL: Access data freely, painlessly, and efficiently." + description: "Apache OpenDAL: access data freely." homepage: https://opendal.apache.org labels: - rust diff --git a/bindings/c/build.rs b/bindings/c/build.rs index 47b27812a6d5..e5b01158f589 100644 --- a/bindings/c/build.rs +++ b/bindings/c/build.rs @@ -17,7 +17,7 @@ extern crate cbindgen; -use std::path::Path; +use std::{path::Path, process::Command}; fn main() { let header_file = Path::new("include").join("opendal.h"); @@ -25,4 +25,12 @@ fn main() { cbindgen::generate(".") .expect("Unable to generate bindings") .write_to_file(header_file); + + Command::new("clang-format") + .arg("--style=WebKit") + .arg("--verbose") + .arg("-i") + .arg("include/opendal.h") + .spawn() + .expect("clang-format must succeed"); } diff --git a/bindings/c/include/opendal.h b/bindings/c/include/opendal.h index e177cb71c1eb..21d9ba4ec146 100644 --- a/bindings/c/include/opendal.h +++ b/bindings/c/include/opendal.h @@ -65,8 +65,7 @@ typedef enum opendal_code { */ OPENDAL_NOT_A_DIRECTORY, /* - The given path already exists thus we failed to the specified operation on - it. + The given path already exists thus we failed to the specified operation on it. */ OPENDAL_ALREADY_EXISTS, /* @@ -160,17 +159,15 @@ extern "C" { #endif // __cplusplus /* - Returns a result type [`opendal_result_op`], with operator_ptr. If the - construction succeeds the error is nullptr, otherwise it contains the error - information. + Returns a result type [`opendal_result_op`], with operator_ptr. If the construction succeeds + the error is nullptr, otherwise it contains the error information. # Safety It is [safe] under two cases below - * The memory pointed to by `scheme` must contain a valid nul terminator at the - end of the string. - * The `scheme` points to NULL, this function simply returns you a null - opendal_operator_ptr + * The memory pointed to by `scheme` must contain a valid nul terminator at the end of + the string. + * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr */ opendal_operator_ptr opendal_operator_new(const char* scheme); @@ -180,14 +177,14 @@ opendal_operator_ptr opendal_operator_new(const char* scheme); void opendal_operator_free(opendal_operator_ptr op_ptr); /* - Write the data into the path blockingly by operator, returns the error code - OPENDAL_OK if succeeds, others otherwise + Write the data into the path blockingly by operator, returns the error code OPENDAL_OK + if succeeds, others otherwise # Safety It is [safe] under two cases below - * The memory pointed to by `path` must contain a valid nul terminator at the - end of the string. + * The memory pointed to by `path` must contain a valid nul terminator at the end of + the string. # Panic @@ -205,15 +202,15 @@ enum opendal_code opendal_operator_blocking_write(opendal_operator_ptr op_ptr, # Safety It is [safe] under two cases below - * The memory pointed to by `path` must contain a valid nul terminator at the - end of the string. + * The memory pointed to by `path` must contain a valid nul terminator at the end of + the string. # Panic * If the `path` points to NULL, this function panics */ -struct opendal_result_read opendal_operator_blocking_read( - opendal_operator_ptr op_ptr, const char* path); +struct opendal_result_read opendal_operator_blocking_read(opendal_operator_ptr op_ptr, + const char* path); /* Check whether the path exists. @@ -226,15 +223,15 @@ struct opendal_result_read opendal_operator_blocking_read( # Safety It is [safe] under two cases below - * The memory pointed to by `path` must contain a valid nul terminator at the - end of the string. + * The memory pointed to by `path` must contain a valid nul terminator at the end of + the string. # Panic * If the `path` points to NULL, this function panics */ -struct opendal_result_is_exist opendal_operator_is_exist( - opendal_operator_ptr op_ptr, const char* path); +struct opendal_result_is_exist opendal_operator_is_exist(opendal_operator_ptr op_ptr, + const char* path); /* Frees the heap memory used by the [`opendal_bytes`] diff --git a/core/README.md b/core/README.md index 7640e64e30ad..8bbce48e84ea 100644 --- a/core/README.md +++ b/core/README.md @@ -8,7 +8,7 @@ [chat]: https://img.shields.io/discord/1081052318650339399 [discord]: https://discord.gg/XQy8yGR2dg -**Open** **D**ata **A**ccess **L**ayer: Access data freely, painlessly, and efficiently +**Open** **D**ata **A**ccess **L**ayer: access data freely. - Documentation: [stable](https://docs.rs/opendal/) | [main](https://opendal.apache.org/docs/rust/opendal/) - [Release notes](https://docs.rs/opendal/latest/opendal/docs/changelog/index.html) diff --git a/core/src/lib.rs b/core/src/lib.rs index b5df5aea0593..bc361738f3d4 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -15,7 +15,7 @@ // specific language governing permissions and limitations // under the License. -//! OpenDAL is the Open Data Access Layer to **freely**, **painlessly**, and **efficiently** access data. +//! OpenDAL is the Open Data Access Layer to **freely** access data. //! //! - Documentation: All docs are carried byself, visit [`docs`] for more. //! - Services: All supported services could be found at [`services`]. diff --git a/website/docs/index.md b/website/docs/index.md new file mode 100644 index 000000000000..2d4a32957009 --- /dev/null +++ b/website/docs/index.md @@ -0,0 +1,76 @@ +--- +title: Overview +sidebar_position: 1 +--- + +**Open** **D**ata **A**ccess **L**ayer: Access data freely. + +![](https://user-images.githubusercontent.com/5351546/222356748-14276998-501b-4d2a-9b09-b8cff3018204.png) + +## Quickstart + +### Rust + +```rust +use opendal::Result; +use opendal::layers::LoggingLayer; +use opendal::services; +use opendal::Operator; + +#[tokio::main] +async fn main() -> Result<()> { + // Pick a builder and configure it. + let mut builder = services::S3::default(); + builder.bucket("test"); + + // Init an operator + let op = Operator::new(builder)? + // Init with logging layer enabled. + .layer(LoggingLayer::default()) + .finish(); + + // Write data + op.write("hello.txt", "Hello, World!").await?; + + // Read data + let bs = op.read("hello.txt").await?; + + // Fetch metadata + let meta = op.stat("hello.txt").await?; + let mode = meta.mode(); + let length = meta.content_length(); + + // Delete + op.delete("hello.txt").await?; + + Ok(()) +} +``` + +### Python + +```python +import asyncio + +async def main(): + op = opendal.AsyncOperator("fs", root="/tmp") + await op.write("test.txt", b"Hello World") + print(await op.read("test.txt")) + +asyncio.run(main()) +``` + +### Node.js + +```js +import { Operator } from "opendal"; + +async function main() { + const op = new Operator("fs", { root: "/tmp" }); + await op.write("test", "Hello, World!"); + const bs = await op.read("test"); + console.log(new TextDecoder().decode(bs)); + const meta = await op.stat("test"); + console.log(`contentLength: ${meta.contentLength}`); +} +``` diff --git a/website/docs/overview.md b/website/docs/overview.md deleted file mode 100644 index 42956286a828..000000000000 --- a/website/docs/overview.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -sidebar_position: 1 -title: Overview ---- diff --git a/website/sidebars.js b/website/docs/sidebars.js similarity index 59% rename from website/sidebars.js rename to website/docs/sidebars.js index 850844c264d1..7704508adcea 100644 --- a/website/sidebars.js +++ b/website/docs/sidebars.js @@ -17,36 +17,11 @@ * under the License. */ -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ - // @ts-check /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], - - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', - { - type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], - }, - ], - */ + docs: [{ type: 'autogenerated', dirName: '.' }], }; module.exports = sidebars; diff --git a/website/docs/vision.md b/website/docs/vision.md new file mode 100644 index 000000000000..dab6e36e17ea --- /dev/null +++ b/website/docs/vision.md @@ -0,0 +1,61 @@ +--- +title: Vision +sidebar_position: 2 +--- + +OpenDAL VISION is: **access data freely**. + +--- + +This is an overview of what the shape of OpenDAL looks like, but also somewhat zoomed out, so that the vision can survive while the exact minute details might shift and change over time. + +## 1. Free from services + +OpenDAL must enable users to access various storage services ranging from `s3` to `dropbox` via it's own native API. It should provide a unified API for accessing all these services. + +### Examples + +- Add support for [Google Drive](https://www.google.com/drive/): Good, it allows users to access and manage their data on the [Google Drive](https://www.google.com/drive/). +- Add support for oss via native API: Good, users can utilize Aliyun's RAM support. +- Add support for [supabase storage](https://supabase.com/docs/guides/storage): Good, users can visit supabase storage now! + + +- Add support for [GCS](https://cloud.google.com/storage) via [XML API](https://cloud.google.com/storage/docs/xml-api/overview): Bad, [GCS](https://cloud.google.com/storage) has native [JSON API](https://cloud.google.com/storage/docs/json_api) which more powerful +- Add support for MySQL/PostgreSQL: Bad, relational DBMS provides data types such as BLOB, but they are often not used as a storage service. + +## 2. Free from implementations + +OpenDAL needs to separate the various implementation details of services and enables users to write identical logic for different services. + +### Examples + +- Add a new capability to indicate whether or not `presign` is supported: Good, users can now write logic based on the `can_presign` option. +- Add a `default_storage_class` configuration for the S3 service: Good, configuration is specific to the s3 service. +- Add an option for `content_type` in the `write` operation: Good, it aligns with HTTP standards. + + +- Add a new option in read for `storage_class`: Bad, as different services could have varying values for this parameter. + +## 3. Free to integrate + +OpenDAL needs to be integrated with different systems. + +### Examples + +- Add python binding: Good, users from `python` can use OpenDAL. +- Add object_store integration: Good, users of `object_store` can adopt OpenDAL. + +## 4. Free to zero cost + +OpenDAL needs to implement features in zero cost way which means: + +- Users don't need to pay cost for not used features. +- Users can't write better implementation for used features. + +### Examples + +- Add `layer` support: Good, users can add logging/metrics/tracing in zero cost way. +- Implement `seek` for Reader: Good, users can't write better `seek` support, they all need to pay the same cost. + + +- Add `Arc` for metadata: Bad, users may only need to use metadata once and never clone it. For those who do want this feature, they can add `Arc` themselves diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 29eb75b3b848..680abdb2d501 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -50,7 +50,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { - sidebarPath: require.resolve('./sidebars.js'), + sidebarPath: require.resolve('./docs/sidebars.js'), editUrl: 'https://github.com/apache/incubator-opendal/website/', showLastUpdateAuthor: true, @@ -90,6 +90,10 @@ const config = { position: 'right', label: 'Documentation', items: [ + { + type: 'html', + value: 'General' + }, { type: 'html', value: 'Rust'