|
| 1 | +package archive |
| 2 | + |
| 3 | +import ( |
| 4 | + "fmt" |
| 5 | + "strconv" |
| 6 | + "strings" |
| 7 | + |
| 8 | + "github.com/donislawdev/TestingFilesGenerator/internal/format" |
| 9 | +) |
| 10 | + |
| 11 | +// Where the files inside an archive sit, and whether the archive lists the |
| 12 | +// directories themselves. |
| 13 | +// |
| 14 | +// Both containers read this one description rather than each growing its own, |
| 15 | +// for the reason the package exists: zip and tar held six constants with |
| 16 | +// identical values and two identical readers before it, and the only thing |
| 17 | +// keeping them equal was a comment. |
| 18 | +// |
| 19 | +// Two settings rather than one, and the pairing is deliberate. A tester asking |
| 20 | +// "does the tool under test cope with nested paths" wants depth. A tester |
| 21 | +// asking "does it cope with an archive that does NOT list its directories" |
| 22 | +// wants the other, because extractors differ: some create a directory when |
| 23 | +// they meet a path that needs one, and some only create what the archive |
| 24 | +// names. An archive is the one format where those are separate questions. |
| 25 | +const ( |
| 26 | + Depth = "depth" |
| 27 | + DirectoryEntries = "directory_entries" |
| 28 | +) |
| 29 | + |
| 30 | +const ( |
| 31 | + // defaultDepth is flat, and it has to stay flat. Every archive this tool |
| 32 | + // has written so far holds its files at the top, so any other default |
| 33 | + // would move the bytes of all of them - untouchable rule 3, and the reason |
| 34 | + // this change needs no version bump at all. |
| 35 | + defaultDepth = 0 |
| 36 | + |
| 37 | + // maxDepth is measured rather than chosen, and the measurement is about |
| 38 | + // tar rather than about taste. |
| 39 | + // |
| 40 | + // targz pins tar.FormatUSTAR (size.go), which carries a path in two |
| 41 | + // fields: a 155 byte prefix and a 100 byte name, split ON A SLASH. So a |
| 42 | + // path is writable when some slash leaves at most 155 before it and at |
| 43 | + // most 100 after it, which is a rule about where the slashes fall and not |
| 44 | + // about length. With the segments below, slashes sit every 4 bytes, the |
| 45 | + // last usable one is at 155, and the path therefore has to come to 256 |
| 46 | + // bytes or fewer: 4*depth + len(entry name) <= 256. |
| 47 | + // |
| 48 | + // Measured 2026-09-01 against Go's own archive/tar with USTAR pinned: |
| 49 | + // depth 61 with a 12 byte name is taken at 256 bytes and depth 62 is |
| 50 | + // REFUSED at 260. The size is flat the whole way - 1536 B at every depth |
| 51 | + // up to the refusal, no hidden step - so the tar arithmetic needs no |
| 52 | + // length term at all. |
| 53 | + // |
| 54 | + // 61 is therefore the ceiling for a 12 byte name and NOT the ceiling to |
| 55 | + // declare, because the entry name is not always 12 bytes. The longest one |
| 56 | + // this build can produce is targz_0001.tar.gz at 17, which lands the limit |
| 57 | + // at 59. Fifty leaves room for a name of 56 bytes, which is far past |
| 58 | + // anything the registry holds, and a guard proves it for every registered |
| 59 | + // format rather than trusting this paragraph. |
| 60 | + maxDepth = 50 |
| 61 | + |
| 62 | + // dirSegment numbers the levels so a path reads as what it is. Two digits |
| 63 | + // because maxDepth is two digits, and a fixed width so every segment is |
| 64 | + // the same size and the arithmetic above stays a multiplication. |
| 65 | + dirSegment = "d%02d/" |
| 66 | + |
| 67 | + // dirSegmentBytes is what one segment comes to once rendered - "d00/" is |
| 68 | + // four bytes where the format string above is six. Written out rather than |
| 69 | + // taken as len(dirSegment), which is the bug the depth guard caught the |
| 70 | + // first time it ran: the arithmetic said every path was 2 bytes per level |
| 71 | + // longer than it is, which would have understated the ceiling rather than |
| 72 | + // overstating it, so nothing would have failed until somebody widened the |
| 73 | + // segment. A guard compares this against a really rendered path. |
| 74 | + dirSegmentBytes = 4 |
| 75 | +) |
| 76 | + |
| 77 | +// Layout is what the two settings come to once read. |
| 78 | +type Layout struct { |
| 79 | + // Depth is how many directories deep the files sit. Zero is flat. |
| 80 | + Depth int |
| 81 | + // DirEntries says whether the archive also names the directories. |
| 82 | + DirEntries bool |
| 83 | +} |
| 84 | + |
| 85 | +// Path is where an entry called name sits under this layout. |
| 86 | +// |
| 87 | +// The empty name gives the directory chain itself with its trailing slash, |
| 88 | +// which is what both containers want a directory entry to be called. |
| 89 | +func (l Layout) Path(name string) string { |
| 90 | + if l.Depth <= 0 { |
| 91 | + return name |
| 92 | + } |
| 93 | + var b strings.Builder |
| 94 | + b.Grow(l.Depth*len(dirSegment) + len(name)) |
| 95 | + for i := 0; i < l.Depth; i++ { |
| 96 | + fmt.Fprintf(&b, dirSegment, i) |
| 97 | + } |
| 98 | + b.WriteString(name) |
| 99 | + return b.String() |
| 100 | +} |
| 101 | + |
| 102 | +// Directories is every directory this layout creates, outermost first. |
| 103 | +// |
| 104 | +// Outermost first because that is the order an extractor wants to meet them |
| 105 | +// in: a reader that creates directories as it goes cannot make d00/d01 before |
| 106 | +// it has made d00. It is empty when nothing was asked for, so a caller can |
| 107 | +// range over it without asking whether the setting is on. |
| 108 | +func (l Layout) Directories() []string { |
| 109 | + if !l.DirEntries || l.Depth <= 0 { |
| 110 | + return nil |
| 111 | + } |
| 112 | + out := make([]string, 0, l.Depth) |
| 113 | + for i := 1; i <= l.Depth; i++ { |
| 114 | + out = append(out, Layout{Depth: i}.Path("")) |
| 115 | + } |
| 116 | + return out |
| 117 | +} |
| 118 | + |
| 119 | +// LongestPath is the longest path this layout can produce for an entry name of |
| 120 | +// the given length. It exists for the guard that proves maxDepth is safe. |
| 121 | +func LongestPath(depth, nameLen int) int { |
| 122 | + return depth*dirSegmentBytes + nameLen |
| 123 | +} |
| 124 | + |
| 125 | +// MaxDepth is the deepest nesting this build offers, for the guard that checks |
| 126 | +// the declaration against what tar will actually take. |
| 127 | +func MaxDepth() int { return maxDepth } |
| 128 | + |
| 129 | +// ReadLayout works out where the files go, and refuses a pair that cannot mean |
| 130 | +// anything. |
| 131 | +// |
| 132 | +// directory_entries with a flat archive is the pair, and it is a refusal |
| 133 | +// rather than a setting quietly doing nothing. There are no directories in a |
| 134 | +// flat archive, so the answer would be the same whichever way it was set - and |
| 135 | +// rule 6 forbids exactly that silence. The message names BOTH halves, because |
| 136 | +// a reader who set one of them cannot tell from "directory_entries is not |
| 137 | +// allowed" which one to change. |
| 138 | +// |
| 139 | +// It is reachable from the window as well as from a recipe, which is why it |
| 140 | +// has to be a good message rather than an internal check: the control is a |
| 141 | +// checkbox, a checkbox always sends its value, and somebody can tick it while |
| 142 | +// depth is still nought. |
| 143 | +func ReadLayout(id string, r format.Request) (Layout, error) { |
| 144 | + depth, err := intProperty(id, r.Properties, Depth, defaultDepth, 0, maxDepth) |
| 145 | + if err != nil { |
| 146 | + return Layout{}, err |
| 147 | + } |
| 148 | + dirs, err := boolProperty(id, r.Properties, DirectoryEntries, false) |
| 149 | + if err != nil { |
| 150 | + return Layout{}, err |
| 151 | + } |
| 152 | + if dirs && depth == 0 { |
| 153 | + return Layout{}, &format.PropertyValueError{ |
| 154 | + Format: id, |
| 155 | + Key: DirectoryEntries, |
| 156 | + Value: "true", |
| 157 | + Reason: "a flat archive has no directories to list, and " + Depth + " is 0", |
| 158 | + Remedy: "Ask for " + Depth + " of 1 or more, or leave " + DirectoryEntries + " off.", |
| 159 | + } |
| 160 | + } |
| 161 | + return Layout{Depth: depth, DirEntries: dirs}, nil |
| 162 | +} |
| 163 | + |
| 164 | +// boolProperty reads a true or false setting. |
| 165 | +// |
| 166 | +// The registry has already refused anything that is not true or false by the |
| 167 | +// time a generator runs, since the declaration says the kind. This repeats the |
| 168 | +// check for the same reason intProperty repeats its range: a caller reaching |
| 169 | +// the generator directly is not going through the registry. |
| 170 | +func boolProperty(id string, props map[string]string, key string, fallback bool) (bool, error) { |
| 171 | + raw, ok := props[key] |
| 172 | + if !ok || raw == "" { |
| 173 | + return fallback, nil |
| 174 | + } |
| 175 | + v, err := strconv.ParseBool(strings.ToLower(raw)) |
| 176 | + if err != nil { |
| 177 | + return false, &format.PropertyValueError{ |
| 178 | + Format: id, |
| 179 | + Key: key, |
| 180 | + Value: raw, |
| 181 | + Reason: "it takes true or false", |
| 182 | + Remedy: "Write " + key + ": true or " + key + ": false.", |
| 183 | + } |
| 184 | + } |
| 185 | + return v, nil |
| 186 | +} |
0 commit comments