Add support for async element writer #635

tevoinea · 2023-08-18T19:37:10Z

This PR adds support for writing to buffers implementing tokio's AsyncWrite. It mirrors the ElementWriter implementation, nearly identically. The only difference is in write_inner_content, the closure needs to return the Writer, I couldn't make the lifetimes line up any other way.

It also includes a full test suite, again mirrored from ElementWriter and docs.

codecov-commenter · 2023-08-18T20:46:32Z

Codecov Report

Merging #635 (e2de822) into master (cced485) will decrease coverage by 0.08%.
The diff coverage is 13.84%.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

@@            Coverage Diff             @@
##           master     #635      +/-   ##
==========================================
- Coverage   64.43%   64.36%   -0.08%     
==========================================
  Files          36       36              
  Lines       17288    17343      +55     
==========================================
+ Hits        11140    11162      +22     
- Misses       6148     6181      +33

Flag	Coverage Δ
unittests	`64.36% <13.84%> (-0.08%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
src/writer/async_tokio.rs	`75.37% <0.00%> (-15.24%)`	⬇️
src/writer.rs	`91.46% <100.00%> (ø)`

... and 1 file with indirect coverage changes

dralley · 2023-08-18T21:02:16Z

src/writer/async_tokio.rs

+    #[tokio::test]
+    async fn element_writer_nested() {
+        let mut buffer = Vec::new();
+        let mut writer = Writer::new_with_indent(&mut buffer, b' ', 4);


I'm fairly certain that the only reason this works is that you're using a buffer type which also implements Write rather than an exclusively-async type.

write_text_content and other methods aren't implemented for ElementWriter<'a, W: AsyncWrite + Unpin>

As a sidenote if you can avoid duplicating the definition of ElementWriter, please do.

I'm fairly certain that the only reason this works is that you're using a buffer type which also implements Write rather than an exclusively-async type.

Good catch! I'll update that

As a sidenote if you can avoid duplicating the definition of ElementWriter, please do.

AFAIK, the only way to do that would be to have an async-only implementation, then have the sync implementation be a wrapper around it. But since async is an optional feature in this crate (and perf is important), I don't think that's the best option.

If there's a better way, I'd love to know! :)

You could remove Write requirement from ElementWriter struct and from impl block for attributes and put Write or AsyncWrite + Unpin to individual impl blocks. Then new functions should be named with _async suffix and no need separate method to create async element writer.

That's a good idea, I like that structure a lot more!

Mingun

Good work! Three issues:

documentation on feature incorrectly formatted
please use modules to grouping tests instead of common prefix
I would prefer to use one ElementWriter struct with sets of methods for sync and async writing

Mingun · 2023-09-12T16:15:23Z

Cargo.toml

+##
+## [writing events] to buffers implementing [`tokio::io::AsyncWrite`].


The ## doc comments is usual rustdoc markdown comments, which is processed by document-features crate. So please rewrite that according to that. If you want to make hyperlink on writing events, please add hyperlink target

I think I maybe misunderstood the docs there so I removed that change.

Mingun · 2023-09-12T16:30:55Z

src/writer/async_tokio.rs

@@ -339,4 +484,93 @@ mod indentation_async {
 </paired>"#
        );
    }
+
+    #[tokio::test]
+    async fn element_writer_empty() {


Instead on using prefix element_writer_ please put all tests i a module element_writer:

mod element_writer { use super::*; use pretty_assertions::assert_eq; #[tokio::test] async fn empty() { ... } ... }

Mingun · 2023-09-12T16:50:47Z

src/writer/async_tokio.rs

+    #[tokio::test]
+    async fn element_writer_nested() {
+        let mut buffer = Vec::new();
+        let mut writer = Writer::new_with_indent(&mut buffer, b' ', 4);


You could remove Write requirement from ElementWriter struct and from impl block for attributes and put Write or AsyncWrite + Unpin to individual impl blocks. Then new functions should be named with _async suffix and no need separate method to create async element writer.

Mingun · 2023-09-14T14:06:58Z

src/writer/async_tokio.rs

@@ -57,6 +60,58 @@ impl<W: AsyncWrite + Unpin> Writer<W> {
        Ok(())
    }

+    // /// Provides a simple, high-level async API for writing XML elements.


Just remove the whole commented block. You always can restore the previous version by checkouting a commit that GitHub shows in a PR

Mingun · 2023-09-14T14:09:04Z

src/writer/async_tokio.rs

+    /// Adds an attribute to this element.
+    pub fn with_attribute_async<'b, I>(mut self, attr: I) -> Self
+    where
+        I: Into<Attribute<'b>>,
+    {
+        self.start_tag.push_attribute(attr);
+        self
+    }
+
+    /// Add additional attributes to this element using an iterator.
+    ///
+    /// The yielded items must be convertible to [`Attribute`] using `Into`.
+    pub fn with_attributes_async<'b, I>(mut self, attributes: I) -> Self
+    where
+        I: IntoIterator,
+        I::Item: Into<Attribute<'b>>,
+    {
+        self.start_tag.extend_attributes(attributes);
+        self
+    }


This methods does not depend from writer, so remove them. Move existing with_attribute and with_attributes methods to the impl block that does not restrict W type parameter, then they will work for both sync and async writers

Since with_attribute is on the ElementWriter, the only way to do this is by removing the Write bound on the ElementWriter struct (in order to support a general impl. I still made the change.

Mingun · 2023-09-14T14:11:18Z

src/writer/async_tokio.rs

+#[cfg(test)]
+mod element_writer {


I supposed that this module will be inside the tests module, but that's also OK

Mingun · 2023-09-14T14:14:30Z

src/writer/async_tokio.rs

+    use pretty_assertions::assert_eq;
+
+    #[tokio::test]
+    async fn empty() {


Hm... maybe move all those tests to doc comments of corresponding methods? I think, this will be useful. This one for write_empty_async

Mingun · 2023-09-14T14:15:02Z

src/writer/async_tokio.rs

+    }
+
+    #[tokio::test]
+    async fn text() {


This for write_text_content_async

Mingun · 2023-09-14T14:15:18Z

src/writer/async_tokio.rs

+    }
+
+    #[tokio::test]
+    async fn nested() {


And this for write_inner_content_async

Mingun

Nice! Only several small nits remained

Mingun · 2023-09-14T15:37:24Z

src/writer/async_tokio.rs

+    ///     std::str::from_utf8(&buffer).unwrap(),
+    ///     r#"<paired attr1="value1" attr2="value2">text</paired>"#
+    /// );
+    /// }


Suggested change

/// }

/// # }

Mingun · 2023-09-14T15:38:48Z

src/writer/async_tokio.rs

+    ///      std::str::from_utf8(&buffer).unwrap(),
+    ///      r#"<empty attr1="value1" attr2="value2"/>"#
+    ///     );
+    /// }


Suggested change

/// }

/// # }

And also please dedent the visible code in example

Mingun · 2023-09-14T15:39:05Z

src/writer/async_tokio.rs

+    ///     </inner>
+    /// </outer>"#
+    ///         );
+    /// }


Suggested change

/// }

/// # }

And also please dedent the visible code in example and check that indent is correct (the first visible line has different indent that the others)

Mingun · 2023-09-14T15:39:55Z

src/writer/async_tokio.rs

+    /// Write some text inside the current element.
+    /// # Example
+    ///
+    /// ```rust


Suggested change

/// ```rust

/// ```

The code blocks already have rust type by default

Mingun · 2023-09-14T15:40:06Z

src/writer/async_tokio.rs

+    /// Write an empty (self-closing) tag.
+    /// # Example
+    ///
+    /// ```rust


Suggested change

/// ```rust

/// ```

The code blocks already have rust type by default

Mingun · 2023-09-14T15:40:17Z

src/writer/async_tokio.rs

+    /// Create a new scope for writing XML inside the current element.
+    /// # Example
+    ///
+    /// ```rust


Suggested change

/// ```rust

/// ```

The code blocks already have rust type by default

Mingun · 2023-09-14T15:47:03Z

Also, please add entry to Changelog.md:

Short description here from line 19:

quick-xml/Changelog.md

Lines 17 to 19 in cced485

    
           - [#545]: Resolve well-known namespaces (`xml` and `xmlns`) to their appropriate URIs. 
        
             Also, enforce namespace constraints related to these well-known namespaces.

A link to this PR here on line 29 (i. e. between two existing links, we keep list of links sorted):

quick-xml/Changelog.md

Lines 28 to 29 in cced485

[#545]: https://github.com/tafia/quick-xml/pull/545

[#643]: https://github.com/tafia/quick-xml/pull/643
(keep two lines between list of links and the previous release section)

Mingun · 2023-09-15T20:36:47Z

Thanks for your work!

Sometimes TortoiseGit loses commits during rebase... What a dangerous bug

dralley reviewed Aug 18, 2023

View reviewed changes

tevoinea requested a review from dralley September 11, 2023 14:10

tevoinea mentioned this pull request Sep 11, 2023

Impl AsyncWrite for cobertura output microsoft/onefuzz#3431

Open

Mingun requested changes Sep 12, 2023

View reviewed changes

tevoinea requested a review from Mingun September 14, 2023 13:56

Mingun requested changes Sep 14, 2023

View reviewed changes

tevoinea force-pushed the tevoinea/AsyncElementWriter branch from 1cc447e to 87bd505 Compare September 14, 2023 16:46

tevoinea requested a review from Mingun September 14, 2023 18:24

Add support for async element writer

e2de822

Mingun force-pushed the tevoinea/AsyncElementWriter branch from 87bd505 to e2de822 Compare September 15, 2023 20:17

Mingun merged commit efb2dc0 into tafia:master Sep 15, 2023
6 checks passed

Mingun added a commit to Mingun/quick-xml that referenced this pull request Sep 18, 2023

Restore lost changelog from tafia#635

1aee1c2

Sometimes TortoiseGit loses commits during rebase... What a dangerous bug

Mingun added a commit to Mingun/quick-xml that referenced this pull request Sep 18, 2023

Restore lost changelog from tafia#635

889541e

Sometimes TortoiseGit loses commits during rebase... What a dangerous bug

Mingun added a commit to Mingun/quick-xml that referenced this pull request Sep 24, 2023

Restore lost changelog from tafia#635

b8f6a1e

Sometimes TortoiseGit loses commits during rebase... What a dangerous bug

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for async element writer #635

Add support for async element writer #635

tevoinea commented Aug 18, 2023 •

edited

Loading

codecov-commenter commented Aug 18, 2023 •

edited

Loading

dralley Aug 18, 2023

tevoinea Aug 22, 2023

Mingun Sep 12, 2023

tevoinea Sep 12, 2023

Mingun left a comment

Mingun Sep 12, 2023

tevoinea Sep 12, 2023

Mingun Sep 12, 2023

Mingun Sep 12, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

tevoinea Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun left a comment

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun Sep 14, 2023

Mingun commented Sep 14, 2023 •

edited

Loading

Mingun commented Sep 15, 2023

		##
		## [writing events] to buffers implementing [`tokio::io::AsyncWrite`].

Add support for async element writer #635

Add support for async element writer #635

Conversation

tevoinea commented Aug 18, 2023 • edited Loading

codecov-commenter commented Aug 18, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mingun left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mingun left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mingun commented Sep 14, 2023 • edited Loading

Mingun commented Sep 15, 2023

tevoinea commented Aug 18, 2023 •

edited

Loading

codecov-commenter commented Aug 18, 2023 •

edited

Loading

Mingun commented Sep 14, 2023 •

edited

Loading