upstream/upstream-seaweedfs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

snapshot of https://github.com/seaweedfs/seaweedfs.git (master, 2026-09-16; blobs > 131072B omitted)
Some checks failed
go: build dev binaries / cleanup (push) Successful in 4s
Details
Codespell / Check for spelling errors (push) Failing after 3s
Details
docker: build dev containers / build-rust-binaries (amd64, x86_64-unknown-linux-musl) (push) Failing after 3s
Details
docker: build dev containers / build-dev-containers (push) Has been skipped
Details
docker: build dev containers / build-rust-binaries (arm64, true, aarch64-unknown-linux-musl) (push) Failing after 3s
Details
End to End / FUSE Mount (push) Failing after 2s
Details
EC Integration Tests / EC Integration Tests (push) Failing after 30s
Details
FUSE DLM Integration Tests / FUSE DLM Integration Tests (push) Failing after 3s
Details
FUSE Volume Server Failover Tests / FUSE Volume Server Failover (push) Failing after 3s
Details
FUSE Integration Tests / FUSE Integration Testing (push) Failing after 2s
Details
FUSE P2P Peer Chunk Sharing Integration Tests / FUSE P2P Peer Chunk Sharing (push) Failing after 3s
Details
go: build binary / Go Vet (push) Failing after 2s
Details
go: build binary / Go Vet 32-bit (push) Failing after 3s
Details
go: build binary / Build (push) Failing after 4s
Details
go: build binary / Build cross-platform (freebsd/amd64) (push) Failing after 3s
Details
go: build binary / Build cross-platform (windows/amd64) (push) Failing after 3s
Details
go: build binary / Build cross-platform (darwin/arm64) (push) Failing after 3s
Details
go: build binary / Build cross-platform (windows/arm64) (push) Failing after 3s
Details
go: build binary / Test (push) Failing after 2s
Details
go: build binary / Test 32-bit (push) Failing after 3s
Details
helm: lint and test charts / lint-test (push) Failing after 3s
Details
Java Client Integration Tests / Java Integration Tests (11) (push) Failing after 3s
Details
Java Client Integration Tests / Java Integration Tests (17) (push) Failing after 3s
Details
go: build dev binaries / build_dev_linux_windows (amd64, linux) (push) Failing after 2s
Details
go: build dev binaries / build_dev_linux_windows (amd64, windows) (push) Failing after 3s
Details
go: build dev binaries / build_dev_darwin (amd64, darwin) (push) Has been skipped
Details
go: build dev binaries / build_dev_darwin (arm64, darwin) (push) Has been skipped
Details
Java Client Unit Tests / Java Unit Tests (11) (push) Failing after 3s
Details
Java Client Unit Tests / Java Unit Tests (17) (push) Failing after 2s
Details
Java Client Unit Tests / Java Unit Tests (21) (push) Failing after 3s
Details
Java Client Unit Tests / Java Unit Tests (8) (push) Failing after 3s
Details
Kafka Quick Test (Load Test with Schema Registry) / Kafka Client Load Test (Quick) (push) Failing after 3s
Details
Kafka Gateway Tests / Kafka Unit Tests (unit-tests-1) (push) Failing after 11s
Details
Kafka Gateway Tests / Kafka Integration Tests (Critical) (integration-1) (push) Failing after 3s
Details
Kafka Gateway Tests / Kafka End-to-End Tests (with SMQ) (e2e-1) (push) Failing after 3s
Details
Kafka Gateway Tests / Kafka Consumer Group Tests (Highly Isolated) (consumer-group-1) (push) Failing after 2s
Details
Kafka Gateway Tests / Kafka Client Compatibility (with SMQ) (client-compat-1) (push) Failing after 3s
Details
Kafka Gateway Tests / Kafka SMQ Integration Tests (Full Stack) (smq-integration-1) (push) Failing after 3s
Details
Kafka Gateway Tests / Kafka Protocol Tests (Isolated) (protocol-1) (push) Failing after 3s
Details
KMS Tests / KMS Provider Integration Tests (push) Failing after 2s
Details
KMS Tests / S3 KMS End-to-End Tests (push) Failing after 3s
Details
Master Cold Start Tests / Master Cold Start Tests (push) Failing after 4s
Details
Metadata Subscribe Integration Tests / Metadata Subscribe Integration Tests (push) Failing after 3s
Details
Multi-Master Tests / Multi-Master Failover Tests (push) Failing after 3s
Details
Performance / CPU and Heap Profile (push) Failing after 2s
Details
Performance / S3 Read/Write Benchmark (rust volume) (push) Failing after 3s
Details
pjdfstest POSIX Compliance / pjdfstest (push) Failing after 2s
Details
Plugin Worker Integration Tests / Plugin Worker: erasure_coding (push) Failing after 3s
Details
Plugin Worker Integration Tests / Plugin Worker: vacuum (push) Failing after 3s
Details
Rust Volume Server Tests / Rust Integration Tests (push) Failing after 3s
Details
Rust Volume Server Tests / Go Tests with Rust Volume (grpc - Shard 1) (push) Failing after 2s
Details
Rust Volume Server Tests / Go Tests with Rust Volume (http - Shard 1) (push) Failing after 3s
Details
Rust Volume Server Tests / Go Tests with Rust Volume (grpc - Shard 2) (push) Failing after 3s
Details
Rust Volume Server Tests / Go Tests with Rust Volume (http - Shard 2) (push) Failing after 3s
Details
Rust Volume Server Tests / Go Tests with Rust Volume (grpc - Shard 3) (push) Failing after 3s
Details
S3 IAM Integration Tests / S3 IAM Distributed Tests (push) Failing after 2s
Details
S3 IAM Integration Tests / S3 IAM Performance Tests (push) Failing after 3s
Details
Performance / Throughput Benchmark (go volume) (push) Failing after 3s
Details
Performance / Throughput Benchmark (rust volume) (push) Failing after 2s
Details
Performance / S3 Read/Write Benchmark (go volume) (push) Failing after 3s
Details
Plugin Worker Integration Tests / Plugin Worker: volume_balance (push) Failing after 3s
Details
PostgreSQL Gateway Tests / PostgreSQL Basic Tests (push) Failing after 3s
Details
Rust Volume Server Tests / Rust Unit Tests (push) Failing after 2s
Details
Rust Volume Server Tests / Go Tests with Rust Volume (http - Shard 3) (push) Failing after 3s
Details
Rust Plugin Worker Tests / Rust Plugin Worker Build and Unit Tests (push) Failing after 3s
Details
rust: build dev volume server binaries / cleanup (push) Successful in 3s
Details
S3 ETag and ACL Tests / S3 ETag + ACL Integration Tests (push) Failing after 3s
Details
S3 IAM Integration Tests / IAM Unit Tests (push) Failing after 3s
Details
S3 IAM Integration Tests / S3 IAM Integration Tests (advanced) (push) Failing after 3s
Details
S3 IAM Integration Tests / S3 IAM Integration Tests (basic) (push) Failing after 2s
Details
S3 IAM Integration Tests / S3 IAM Integration Tests (group) (push) Failing after 3s
Details
S3 IAM Integration Tests / S3 IAM Integration Tests (policy-enforcement) (push) Failing after 2s
Details
S3 IAM Integration Tests / S3 IAM Integration Tests (sts) (push) Failing after 4s
Details
S3 Keycloak Integration Tests / S3 Keycloak Integration Tests (push) Failing after 3s
Details
S3 PyArrow Parquet Tests / PyArrow Parquet Tests (Python 3.11) (push) Failing after 3s
Details
S3 PyArrow Parquet Tests / Go Unit Tests (Implicit Directory) (push) Has been cancelled
Details
S3 PyArrow Parquet Tests / PyArrow Parquet Tests (Python 3.12) (push) Has been cancelled
Details
rust: build dev volume server binaries / build-rust-volume-dev-darwin (darwin-amd64, x86_64-apple-darwin) (push) Has been cancelled
Details
rust: build dev volume server binaries / build-rust-volume-dev-darwin (darwin-arm64, aarch64-apple-darwin) (push) Has been cancelled
Details
rust: build dev volume server binaries / build-rust-volume-dev-linux (linux-amd64, x86_64-unknown-linux-gnu) (push) Has been cancelled
Details
S3 PyArrow Parquet Tests / PyArrow Parquet Tests (Python 3.9) (push) Has been cancelled
Details
S3 Proxy Signature Tests / S3 Proxy Signature Verification Tests (push) Has been cancelled
Details
S3 SDK V2 Route Disambiguation Tests / S3 SDK V2 Routing Tests (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Integration Tests (quick) (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Compatibility Test (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Metadata Persistence Test (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Copy Operations Test (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Multipart Upload Test (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Performance Test (push) Has been cancelled
Details
S3 SSE Tests / S3 Volume Encryption Test (push) Has been cancelled
Details
S3 SSE Tests / S3 SSE Integration Tests (comprehensive) (push) Has been cancelled
Details
Spark Integration Tests / Spark Integration Tests (push) Failing after 2s
Details
Telemetry Integration Tests / telemetry-integration-test (push) Failing after 3s
Details
Volume Server Integration Tests / Volume Server Integration Tests (grpc - Shard 1) (push) Failing after 3s
Details
Volume Server Integration Tests / Volume Server Integration Tests (http - Shard 1) (push) Failing after 3s
Details
Ceph S3 tests / Basic S3 tests (KV store) (push) Has been cancelled
Details
Ceph S3 tests / S3 Versioning & Object Lock tests (push) Has been cancelled
Details
S3 Policy Integration Tests / S3 Policy Unit Tests (push) Failing after 3s
Details
Ceph S3 tests / S3 CORS tests (push) Has been cancelled
Details
Ceph S3 tests / SeaweedFS Custom S3 Copy tests (push) Has been cancelled
Details
Ceph S3 tests / Basic S3 tests (SQL store) (push) Has been cancelled
Details
test s3 over https using aws-cli / awscli-tests (push) Has been cancelled
Details
TLS Rotation Integration Tests / TLS Rotation Integration Tests (push) Has been cancelled
Details
Vacuum Integration Tests / Vacuum Integration Tests (push) Has been cancelled
Details
S3 Policy Integration Tests / S3 Policy Variables Integration Tests (push) Failing after 3s
Details
S3 Policy Integration Tests / S3 Policy Enforcement Integration Tests (advanced-policy) (push) Failing after 3s
Details
S3 Policy Integration Tests / S3 Policy Enforcement Integration Tests (basic-policy) (push) Failing after 2s
Details
S3 Policy Integration Tests / S3 Policy Enforcement Integration Tests (contextual-policy) (push) Failing after 4s
Details
S3 Policy Integration Tests / Trusted Proxy Detection Tests (push) Failing after 2s
Details
S3 Policy Integration Tests / S3 Policy Shell Integration Tests (push) Failing after 3s
Details
Samba on FUSE Integration / samba-integration (push) Failing after 2s
Details
SFTP Integration Tests / SFTP Integration Testing (push) Failing after 3s
Details
terraform: validate and test modules / fmt, validate, plan-level tests (push) Failing after 3s
Details
terraform: validate and test modules / local cluster smoke test (real weed) (push) Failing after 2s
Details
Volume Server Integration Tests / Volume Server Integration Tests (grpc - Shard 3) (push) Failing after 3s
Details
Volume Server Integration Tests / Volume Server Integration Tests (grpc - Shard 2) (push) Failing after 3s
Details
Volume Server Integration Tests / Volume Server Integration Tests (http - Shard 2) (push) Failing after 2s
Details
Volume Server Integration Tests / Volume Server Integration Tests (http - Shard 3) (push) Failing after 5s
Details
mount: windows conformance / WinFsp conformance (push) Has been cancelled
Details
mount: windows / Mount on Windows (push) Has been cancelled
Details

Browse Source
This commit is contained in:
upstream-mirror
2026-09-16 03:23:42 +05:00
commit 89f5be005d
3997 changed files with 961970 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
weed/storage/needle/README.md Normal file
View File

@@ -0,0 +1,160 @@
# Needle Layout Format
This document describes the binary layout of the Needle structure as used in SeaweedFS storage, for all supported versions (v1, v2, v3).
A Needle represents a file or data blob stored in a volume file. The layout determines how the Needle is serialized to disk for efficient storage and retrieval.
---
## Common Field Sizes
| Field | Size (bytes) |
|---------------|--------------|
| Cookie | 4 |
| NeedleId | 8 |
| Size | 4 |
| DataSize | 4 |
| Flags | 1 |
| NameSize | 1 |
| MimeSize | 1 |
| LastModified | 5 |
| Ttl | 2 |
| PairsSize | 2 |
| Checksum | 4 |
| Timestamp | 8 |
---
## Needle Layouts by Version
### Version 1
| Offset | Field | Size (bytes) | Description |
|----------|----------|--------------|-----------------------------------------------|
| 0 | Cookie | 4 | Random number to mitigate brute force lookups |
| 4 | Id | 8 | Needle ID |
| 12 | Size | 4 | Length of Data |
| 16 | Data | N | File data (N = Size) |
| 16+N | Checksum | 4 | CRC32 of Data |
| 20+N | Padding | 0-7 | To align to 8 bytes |
### Version 2
| Offset | Field | Size (bytes) | Description |
|----------|-------------|--------------|-----------------------------------------------|
| 0 | Cookie | 4 | Random number |
| 4 | Id | 8 | Needle ID |
| 12 | Size | 4 | Total size of the following fields |
| 16 | DataSize | 4 | Length of Data (N) |
| 20 | Data | N | File data |
| 20+N | Flags | 1 | Bit flags |
| 21+N | NameSize | 1 (opt) | Optional, if present |
| 22+N | Name | M (opt) | Optional, if present (M = NameSize) |
| ... | MimeSize | 1 (opt) | Optional, if present |
| ... | Mime | K (opt) | Optional, if present (K = MimeSize) |
| ... | LastModified| 5 (opt) | Optional, if present |
| ... | Ttl | 2 (opt) | Optional, if present |
| ... | PairsSize | 2 (opt) | Optional, if present |
| ... | Pairs | P (opt) | Optional, if present (P = PairsSize) |
| ... | Checksum | 4 | CRC32 |
| ... | Padding | 0-7 | To align to 8 bytes |
### Version 3
| Offset | Field | Size (bytes) | Description |
|----------|-------------|--------------|-----------------------------------------------|
| 0 | Cookie | 4 | Random number |
| 4 | Id | 8 | Needle ID |
| 12 | Size | 4 | Total size of the following fields |
| 16 | DataSize | 4 | Length of Data (N) |
| 20 | Data | N | File data |
| 20+N | Flags | 1 | Bit flags |
| 21+N | NameSize | 1 (opt) | Optional, if present |
| 22+N | Name | M (opt) | Optional, if present (M = NameSize) |
| ... | MimeSize | 1 (opt) | Optional, if present |
| ... | Mime | K (opt) | Optional, if present (K = MimeSize) |
| ... | LastModified| 5 (opt) | Optional, if present |
| ... | Ttl | 2 (opt) | Optional, if present |
| ... | PairsSize | 2 (opt) | Optional, if present |
| ... | Pairs | P (opt) | Optional, if present (P = PairsSize) |
| ... | Checksum | 4 | CRC32 |
| ... | Timestamp | 8 | Append time in nanoseconds |
| ... | Padding | 0-7 | To align to 8 bytes |
- Offsets marked with `...` depend on the presence and size of previous optional fields.
- Fields marked `(opt)` are optional and only present if the corresponding size or flag is non-zero.
- N = DataSize, M = NameSize, K = MimeSize, P = PairsSize.
---
## Field Explanations
- **Cookie**: 4 bytes, random value for security.
- **Id**: 8 bytes, unique identifier for the Needle.
- **Size**: 4 bytes, total size of the Needle data section (not including header, checksum, timestamp, or padding).
- **DataSize**: 4 bytes, length of the Data field.
- **Data**: File data (variable length).
- **Flags**: 1 byte, bit flags for Needle properties.
- **NameSize/Name**: 1 byte + variable, optional file name.
- **MimeSize/Mime**: 1 byte + variable, optional MIME type.
- **LastModified**: 5 bytes, optional last modified timestamp.
- **Ttl**: 2 bytes, optional time-to-live.
- **PairsSize/Pairs**: 2 bytes + variable, optional key-value pairs.
- **Checksum**: 4 bytes, CRC32 checksum of the Needle data.
- **Timestamp**: 8 bytes, append time (only in v3).
- **Padding**: 0-7 bytes, to align the total Needle size to 8 bytes.
---
## Version Comparison Table
| Field | v1 | v2 | v3 |
|---------------|----|----|----|
| Cookie | ✔ | ✔ | ✔ |
| Id | ✔ | ✔ | ✔ |
| Size | ✔ | ✔ | ✔ |
| DataSize | | ✔ | ✔ |
| Data | ✔ | ✔ | ✔ |
| Flags | | ✔ | ✔ |
| NameSize/Name | | ✔ | ✔ |
| MimeSize/Mime | | ✔ | ✔ |
| LastModified | | ✔ | ✔ |
| Ttl | | ✔ | ✔ |
| PairsSize/Pairs| | ✔ | ✔ |
| Checksum | ✔ | ✔ | ✔ |
| Timestamp | | | ✔ |
| Padding | ✔ | ✔ | ✔ |
---
## Flags Field Details
The `Flags` field (present in v2 and v3) is a bitmask that encodes several boolean properties of the Needle. Each bit has a specific meaning:
| Bit Value | Name | Meaning |
|-----------|-----------------------|--------------------------------------------------------------|
| 0x01 | FlagIsCompressed | Data is compressed (isCompressed) |
| 0x02 | FlagHasName | Name field is present (NameSize/Name) |
| 0x04 | FlagHasMime | Mime field is present (MimeSize/Mime) |
| 0x08 | FlagHasLastModifiedDate| LastModified field is present |
| 0x10 | FlagHasTtl | Ttl field is present |
| 0x20 | FlagHasPairs | Pairs field is present (PairsSize/Pairs) |
| 0x80 | FlagIsChunkManifest | Data is a chunk manifest (for large files) |
- If a flag is set, the corresponding field(s) will appear in the Needle layout at the appropriate position.
- The `Flags` field is always present in v2 and v3, immediately after the Data field.
## Optional Fields
- Fields marked as optional in the layout tables are only present if the corresponding flag in the `Flags` field is set (except for Name/Mime/Pairs, which also depend on their size fields being non-zero).
- The order of optional fields is fixed and matches the order of their flags.
## Special Notes
- **isCompressed**: If set, the Data field is compressed (typically using gzip). This is indicated by the lowest bit (0x01) in the Flags byte.
- **isChunkManifest**: If set, the Data field contains a manifest describing chunks of a large file, not raw file data.
- **All multi-byte fields** are stored in big-endian order.
- **Padding** is always added at the end to align the total Needle size to 8 bytes.
- **N = DataSize, M = NameSize, K = MimeSize, P = PairsSize** in the layout tables above.
For more details, see the implementation in the corresponding Go files in this directory.