This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch add-vision in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit 475cc11dcfb245a62a6115d1234bef8965009711 Author: Xuanwo <[email protected]> AuthorDate: Sun Apr 16 11:44:07 2023 +0800 docs: Add OpenDAL VISION Signed-off-by: Xuanwo <[email protected]> --- .asf.yaml | 2 +- bindings/c/include/opendal.h | 160 ++++++++++++++++++++--------------------- core/README.md | 2 +- core/src/lib.rs | 2 +- website/docs/index.md | 76 ++++++++++++++++++++ website/docs/overview.md | 4 -- website/{ => docs}/sidebars.js | 27 +------ website/docs/vision.md | 54 ++++++++++++++ website/docusaurus.config.js | 6 +- 9 files changed, 218 insertions(+), 115 deletions(-) diff --git a/.asf.yaml b/.asf.yaml index c6ff7d55..730f0b35 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/include/opendal.h b/bindings/c/include/opendal.h index e177cb71..f4ad4704 100644 --- a/bindings/c/include/opendal.h +++ b/bindings/c/include/opendal.h @@ -17,66 +17,66 @@ * under the License. */ + #ifndef _OPENDAL_H #define _OPENDAL_H -#include <stdbool.h> -#include <stddef.h> #include <stdint.h> +#include <stddef.h> +#include <stdbool.h> /* The error code for opendal APIs in C binding */ typedef enum opendal_code { - /* - All is well - */ - OPENDAL_OK, - /* - General error - */ - OPENDAL_ERROR, - /* - returning it back. For example, s3 returns an internal service error. - */ - OPENDAL_UNEXPECTED, - /* - Underlying service doesn't support this operation. - */ - OPENDAL_UNSUPPORTED, - /* - The config for backend is invalid. - */ - OPENDAL_CONFIG_INVALID, - /* - The given path is not found. - */ - OPENDAL_NOT_FOUND, - /* - The given path doesn't have enough permission for this operation - */ - OPENDAL_PERMISSION_DENIED, - /* - The given path is a directory. - */ - OPENDAL_IS_A_DIRECTORY, - /* - The given path is not a directory. - */ - OPENDAL_NOT_A_DIRECTORY, - /* - The given path already exists thus we failed to the specified operation on - it. - */ - OPENDAL_ALREADY_EXISTS, - /* - Requests that sent to this path is over the limit, please slow down. - */ - OPENDAL_RATE_LIMITED, - /* - The given file paths are same. - */ - OPENDAL_IS_SAME_FILE, + /* + All is well + */ + OPENDAL_OK, + /* + General error + */ + OPENDAL_ERROR, + /* + returning it back. For example, s3 returns an internal service error. + */ + OPENDAL_UNEXPECTED, + /* + Underlying service doesn't support this operation. + */ + OPENDAL_UNSUPPORTED, + /* + The config for backend is invalid. + */ + OPENDAL_CONFIG_INVALID, + /* + The given path is not found. + */ + OPENDAL_NOT_FOUND, + /* + The given path doesn't have enough permission for this operation + */ + OPENDAL_PERMISSION_DENIED, + /* + The given path is a directory. + */ + OPENDAL_IS_A_DIRECTORY, + /* + The given path is not a directory. + */ + OPENDAL_NOT_A_DIRECTORY, + /* + The given path already exists thus we failed to the specified operation on it. + */ + OPENDAL_ALREADY_EXISTS, + /* + Requests that sent to this path is over the limit, please slow down. + */ + OPENDAL_RATE_LIMITED, + /* + The given file paths are same. + */ + OPENDAL_IS_SAME_FILE, } opendal_code; /* @@ -121,7 +121,7 @@ typedef struct BlockingOperator BlockingOperator; to check its validity by native boolean operator. e.g. you could check by (!ptr) on a [`opendal_operator_ptr`] */ -typedef const struct BlockingOperator* opendal_operator_ptr; +typedef const struct BlockingOperator *opendal_operator_ptr; /* The [`opendal_bytes`] type is a C-compatible substitute for [`Vec`] @@ -130,8 +130,8 @@ typedef const struct BlockingOperator* opendal_operator_ptr; to free the heap memory to avoid memory leak. */ typedef struct opendal_bytes { - const uint8_t* data; - uintptr_t len; + const uint8_t *data; + uintptr_t len; } opendal_bytes; /* @@ -141,8 +141,8 @@ typedef struct opendal_bytes { and the error code is NOT OPENDAL_OK. */ typedef struct opendal_result_read { - struct opendal_bytes* data; - enum opendal_code code; + struct opendal_bytes *data; + enum opendal_code code; } opendal_result_read; /* @@ -151,8 +151,8 @@ typedef struct opendal_result_read { corresponding error code. */ typedef struct opendal_result_is_exist { - bool is_exist; - enum opendal_code code; + bool is_exist; + enum opendal_code code; } opendal_result_is_exist; #ifdef __cplusplus @@ -160,19 +160,17 @@ 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); +opendal_operator_ptr opendal_operator_new(const char *scheme); /* Free the allocated operator pointed by [`opendal_operator_ptr`] @@ -180,22 +178,22 @@ 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 * If the `path` points to NULL, this function panics */ enum opendal_code opendal_operator_blocking_write(opendal_operator_ptr op_ptr, - const char* path, - struct opendal_bytes bytes); + const char *path, + struct opendal_bytes bytes); /* Read the data out from path into a [`Bytes`] blockingly by operator, returns @@ -205,15 +203,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,20 +224,20 @@ 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`] */ -void opendal_bytes_free(const struct opendal_bytes* self); +void opendal_bytes_free(const struct opendal_bytes *self); #ifdef __cplusplus } // extern "C" diff --git a/core/README.md b/core/README.md index 7640e64e..8bbce48e 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 b5df5aea..bc361738 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 00000000..2d4a3295 --- /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. + + + +## 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 42956286..00000000 --- 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 850844c2..7704508a 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 00000000..babf2651 --- /dev/null +++ b/website/docs/vision.md @@ -0,0 +1,54 @@ +--- +title: Vision +sidebar_position: 2 +--- + +OpenDAL VISION: **access data freely**. + +### 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. + +- Add support for google drive: Good, it allows users to access and manage their data on the google 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 sotrage now! + + +- Add support for gcs via XML API: Bad, gcs has native 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. + +### Free from implementations + +OpenDAL needs to separate the various implementation details of services and enables users to write identical logic for different services. + +- 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. + +### Free to integrate + +OpenDAL needs to be integrated with different systems. + +- Add python binding: Good, users from `python` can use OpenDAL. +- Add object_store integration: Good, users of `object_store` can adopt OpenDAL. + + +- Rewrite OpenDAL in Golang: Good idea itself, but not related to OpenDAL. + +### 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. + +For 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 29eb75b3..680abdb2 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: '<a class="dropdown__link" href="/docs">General</a>' + }, { type: 'html', value: '<a class="dropdown__link" href="/docs/rust/opendal">Rust</a>'
