blob: 0740854545fcd5d1603ece7c159fd42511a22dc8 [file] [log] [blame]
// Copyright 2019 The Wuffs Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------
// Package rac provides access to RAC (Random Access Compression) files.
//
// RAC is just a container format, and this package ("rac") is a relatively
// low-level. Users will typically want to process a particular compression
// format wrapped in RAC, such as (RAC + Zlib). For that, look at e.g. the
// sibling "raczlib" package.
//
// The RAC specification is at
// https://github.com/google/wuffs/blob/main/doc/spec/rac-spec.md
package rac
import (
"errors"
)
const (
// MaxSize is the maximum RAC file size (in both CSpace and DSpace).
MaxSize = (1 << 48) - 1
// invalidCOffsetCLength is ((1 << 64) - 1).
invalidCOffsetCLength = 0xFFFFFFFFFFFFFFFF
)
// Codec is the compression codec for the RAC file.
//
// For leaf nodes, there are two categories of valid Codecs: Short and Long. A
// Short Codec's uint64 value's high 2 bits and low 56 bits must be zero. A
// Long Codec's uint64 value's high 8 bits must be one and then 7 zeroes.
// Symbolically, Short and Long match:
// - 0b00??????_00000000_00000000_00000000_00000000_00000000_00000000_00000000
// - 0b10000000_????????_????????_????????_????????_????????_????????_????????
//
// In terms of the RAC file format, a Short Codec fits in a single byte: the
// Codec Byte in the middle of a branch node. A Long Codec uses that Codec Byte
// to locate 7 other bytes, a location which would otherwise form a "CPtr|CLen"
// value. When converting from the 7 bytes in the wire format to this Go type
// (a uint64 value), they are read little-endian: the "CPtr" bytes are the low
// 6 bytes, the "CLen" is the second-highest byte and the highest byte is
// hard-coded to 0x80.
//
// For example, the 7 bytes "mdo2\x00\x00\x00" would correspond to a Codec
// value of 0x8000_0000_326F_646D.
//
// The Mix Bit is not part of the uint64 representation. Neither is a Long
// Codec's 'c64' index. This package's exported API deals with leaf nodes.
// Branch nodes' wire formats are internal implementation details.
//
// See the RAC specification for further discussion.
type Codec uint64
func (c Codec) isLong() bool { return int64(c) < 0 }
func (c Codec) isShort() bool { return int64(c) >= 0 }
// Valid returns whether c matches the Short or Long pattern.
func (c Codec) Valid() bool {
if (c >> 63) == 0 {
return ((c << 8) == 0) && ((c >> 62) == 0)
}
return (c >> 56) == 0x80
}
func (c Codec) name() string {
if c.isShort() && c.Valid() {
switch c >> 56 {
case 0:
return "Zeroes"
case 1:
return "Zlib"
case 2:
return "LZ4"
case 3:
return "Zstandard"
}
}
return ""
}
func parentChildCodecsValid(parent Codec, child Codec, parentHasMixBit bool) bool {
return (parent == child) || parentHasMixBit
}
const (
CodecZeroes = Codec(0x00 << 56)
CodecZlib = Codec(0x01 << 56)
CodecLZ4 = Codec(0x02 << 56)
CodecZstandard = Codec(0x03 << 56)
codecMixBit = Codec(1 << 62)
codecLongZeroes = Codec(1 << 63)
CodecInvalid = Codec((1 << 64) - 1)
)
// IndexLocation is whether the index is at the start or end of the RAC file.
//
// See the RAC specification for further discussion.
type IndexLocation uint8
const magic = "\x72\xC3\x63"
const (
IndexLocationAtEnd = IndexLocation(0)
IndexLocationAtStart = IndexLocation(1)
)
var indexLocationAtEndMagic = []byte("\x72\xC3\x63\x00")
var (
ErrCodecWriterDoesNotSupportCChunkSize = errors.New("rac: CodecWriter does not support CChunkSize")
errAlreadyClosed = errors.New("rac: already closed")
errCChunkSizeIsTooSmall = errors.New("rac: CChunkSize is too small")
errILAEndTempFile = errors.New("rac: IndexLocationAtEnd requires a nil TempFile")
errILAStartTempFile = errors.New("rac: IndexLocationAtStart requires a non-nil TempFile")
errInconsistentCompressedSize = errors.New("rac: inconsistent compressed size")
errInvalidCPageSize = errors.New("rac: invalid CPageSize")
errInvalidChunk = errors.New("rac: invalid chunk")
errInvalidChunkTooLarge = errors.New("rac: invalid chunk (too large)")
errInvalidChunkTruncated = errors.New("rac: invalid chunk (truncated)")
errInvalidCodec = errors.New("rac: invalid Codec")
errInvalidCodecWriter = errors.New("rac: invalid CodecWriter")
errInvalidCompressedSize = errors.New("rac: invalid CompressedSize")
errInvalidIndexNode = errors.New("rac: invalid index node")
errInvalidInputMissingMagicBytes = errors.New("rac: invalid input: missing magic bytes")
errInvalidInputMissingRootNode = errors.New("rac: invalid input: missing root node")
errInvalidReadSeeker = errors.New("rac: invalid ReadSeeker")
errInvalidWriter = errors.New("rac: invalid Writer")
errSeekToInvalidWhence = errors.New("rac: seek to invalid whence")
errSeekToNegativePosition = errors.New("rac: seek to negative position")
errSeekToNegativeRange = errors.New("rac: seek to negative range")
errTooManyChunks = errors.New("rac: too many chunks")
errTooManyResources = errors.New("rac: too many resources")
errTooMuchInput = errors.New("rac: too much input")
errUnsupportedRACFileVersion = errors.New("rac: unsupported RAC file version")
errInternalArityIsTooLarge = errors.New("rac: internal error: arity is too large")
errInternalEmptyDRange = errors.New("rac: internal error: empty DRange")
errInternalInconsistentArity = errors.New("rac: internal error: inconsistent arity")
errInternalInconsistentPosition = errors.New("rac: internal error: inconsistent position")
errInternalShortCSize = errors.New("rac: internal error: short CSize")
)