tar: Only pad partially-filled blocks (#67)

Motivation
----------

Tar archives are stored sequences of 512-byte blocks, so archive members
must be zero-padded to the nearest whole number of blocks. The current
padding calculation incorrectly adds a full 512-byte padding block if
the member already finishes on a block boundary.

The tar end of file marker is defined as two consecutive empty blocks:

   https://www.loc.gov/preservation/digital/formats/fdd/fdd000531.shtml

However interoperability testing with the system tar binary shows that a
single unnecessary empty block will be interpreted as the end of the
file.

Modifications
-------------

The padding calculation now correctly avoids zero-padding a file which
is already a whole number of blocks in length.

Result
------

* Tar archives produced by the `Tar` module will match the out put of
the system tar utilities.
* This commit will not immediately cause a noticeable change in
behaviour because `containertool` currently only stores one member - the
application binary - in an archive.

Test Plan
---------

* New tests check that padding is only applied to partially full blocks.
* All existing tests continue to pass.

Author: euanh

Sources/Tar/tar.swift

@@ -201,6 +201,16 @@ public func tarHeader(filesize: Int, filename: String = "app") throws -> [UInt8]
     return hdr
 }
 
+let blockSize = 512
+
+/// Returns the number of padding bytes to be appended to a file.
+/// Each file in a tar archive must be padded to a multiple of the 512 byte block size.
+/// - Parameter len: The length of the archive member.
+/// - Returns: The number of zero bytes to append as padding.
+func padding(_ len: Int) -> Int {
+    (blockSize - len % blockSize) % blockSize
+}
+
 /// Creates a tar archive containing a single file
 /// - Parameters:
 ///   - bytes: The file's body data
@@ -214,7 +224,7 @@ public func tar(_ bytes: [UInt8], filename: String = "app") throws -> [UInt8] {
     hdr.append(contentsOf: bytes)
 
     // Pad the file data to a multiple of 512 bytes
-    let padding = [UInt8](repeating: 0, count: 512 - (bytes.count % 512))
+    let padding = [UInt8](repeating: 0, count: padding(bytes.count))
     hdr.append(contentsOf: padding)
 
     // Append the end of file marker

Tests/TarTests/TarUnitTests.swift

@@ -42,6 +42,30 @@ let trailerLen = 2 * blocksize
         #expect(octal11(input) == expected)
     }
 
+    // We should never add a full block (512 bytes) of padding
+    @Test(arguments: [
+        (input: 0, expected: 0),
+        (input: 1, expected: 511),
+        (input: 2, expected: 510),
+        (input: 511, expected: 1),
+        (input: 512, expected: 0),
+        (input: 513, expected: 511),
+    ])
+    func testPadded(input: Int, expected: Int) async throws {
+        #expect(padding(input) == expected)
+    }
+
+    @Test(arguments: 0...1025)
+    func testPaddedProperties(input: Int) async throws {
+        let output = padding(input)
+
+        // The padded output should be a whole number of blocks
+        #expect((input + output) % 512 == 0)
+
+        // We should never write a full block of padding, because tar considers this to be the end of the file
+        #expect(output < 512)
+    }
+
     @Test func testUInt8writeString() async throws {
         // Fill the buffer with 0xFF to show null termination
         var hdr = [UInt8](repeating: 255, count: 21)