/src/trafficserver/include/config/storage.h

Source
/** @file

  Storage configuration parsing and marshalling.

  @section license License

  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you 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

      http://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.
*/

#pragma once

#include <cstdint>
#include <string>
#include <string_view>
#include <vector>

#include "config/config_result.h"

namespace config
{

/**
 * Represents a single storage span entry in storage.yaml.
 */
struct StorageSpanEntry {
  std::string name;
  std::string path;
  std::string hash_seed; ///< optional
  int64_t     size = 0;  ///< optional for raw device
};

/**
 * Represents a single volume entry in storage.yaml.
 */
struct StorageVolumeEntry {
  struct Size {
    int64_t absolute_value = 0;
    bool    in_percent     = false;
    int     percent        = 0;

    bool
    is_empty() const
    {
      return !in_percent && absolute_value == 0;
    }
  };

  struct SpanRef {
    std::string use;
    Size        size;
  };

  int                  id     = 0;
  std::string          scheme = "http";
  Size                 size;
  bool                 ram_cache        = true;
  int64_t              ram_cache_size   = -1;
  int64_t              ram_cache_cutoff = -1;
  int                  avg_obj_size     = -1;
  int                  fragment_size    = -1;
  std::vector<SpanRef> spans;
};

/**
 * Top-level storage configuration.
 */
struct StorageConfig {
  std::vector<StorageSpanEntry>   spans;
  std::vector<StorageVolumeEntry> volumes;
};

/**
 * Parser for storage.yaml / storage.config configuration files.
 *
 * Supports both the current YAML format (storage.yaml) and the legacy
 * line-based format (storage.config).  The format is auto-detected by
 * file extension when parse() is used: files ending in ".yaml" are
 * parsed as YAML; all others are parsed as legacy storage.config.
 */
class StorageParser
{
public:
  /**
   * Parse a storage configuration file.
   *
   * Files ending in ".yaml" are parsed as YAML (storage.yaml); all other
   * files are parsed using the legacy storage.config line-based format.
   *
   * @param[in] filename Path to the configuration file.
   * @return ConfigResult containing the parsed configuration or errors.
   */
  ConfigResult<StorageConfig> parse(std::string const &filename);

  /**
   * Parse storage.yaml content from a string (useful for unit tests).
   *
   * @param[in] content The YAML content to parse.
   * @return ConfigResult containing the parsed configuration or errors.
   */
  ConfigResult<StorageConfig> parse_content(std::string_view content);

  /**
   * Parse legacy storage.config content from a string.
   *
   * Each non-blank, non-comment line has the form:
   *   pathname [size_bytes] [id=hash_seed] [volume=N]
   *
   * Spans whose lines carry a "volume=N" annotation produce a
   * StorageVolumeEntry with id=N and a span-ref to the span.
   *
   * @param[in] content The legacy storage.config content to parse.
   * @return ConfigResult containing the parsed configuration or errors.
   */
  ConfigResult<StorageConfig> parse_legacy_storage_content(std::string_view content);
};

/**
 * Parser for the legacy volume.config configuration file.
 *
 * Each non-blank, non-comment line has the form:
 *   volume=N scheme=http size=V[%] [avg_obj_size=V] [fragment_size=V]
 *                                  [ramcache=true|false]
 *                                  [ram_cache_size=V] [ram_cache_cutoff=V]
 *
 * Absolute sizes are in megabytes; percent sizes are written as "N%".
 */
class VolumeParser
{
public:
  /**
   * Parse a volume.config file.
   *
   * @param[in] filename Path to the configuration file.
   * @return ConfigResult whose value has only the volumes field populated.
   */
  ConfigResult<StorageConfig> parse(std::string const &filename);

  /**
   * Parse legacy volume.config content from a string (useful for unit tests).
   *
   * @param[in] content The legacy volume.config content to parse.
   * @return ConfigResult whose value has only the volumes field populated.
   */
  ConfigResult<StorageConfig> parse_content(std::string_view content);
};

/**
 * Merge a legacy storage.config result with a legacy volume.config result.
 *
 * The spans come from @a storage (the storage.config parse result).
 * If @a volumes contains any volume entries (the volume.config parse result),
 * they replace the minimal volume entries produced by storage.config
 * "volume=N" annotations, while preserving the span-ref associations that
 * those annotations recorded.  If @a volumes is empty, the partial volume
 * entries from @a storage are kept as-is.
 *
 * @param[in] storage  Result of StorageParser::parse_legacy_storage_content().
 * @param[in] volumes  Result of VolumeParser::parse_content() (may be empty).
 * @return Merged StorageConfig ready for marshalling.
 */
StorageConfig merge_legacy_storage_configs(StorageConfig const &storage, StorageConfig const &volumes);

/**
 * Marshaller for storage configuration.
 *
 * Serializes configuration to YAML or JSON format.
 */
class StorageMarshaller
{
public:
  /**
   * Serialize configuration to YAML format.
   *
   * @param[in] config The configuration to serialize.
   * @return YAML string representation.
   */
  std::string to_yaml(StorageConfig const &config);

  /**
   * Serialize configuration to JSON format.
   *
   * @param[in] config The configuration to serialize.
   * @return JSON string representation.
   */
  std::string to_json(StorageConfig const &config);
};

} // namespace config

Coverage Report

Created: 2026-10-23 06:28

Line	Count	Source
1		/** @file
2
3		Storage configuration parsing and marshalling.
4
5		@section license License
6
7		Licensed to the Apache Software Foundation (ASF) under one
8		or more contributor license agreements. See the NOTICE file
9		distributed with this work for additional information
10		regarding copyright ownership. The ASF licenses this file
11		to you under the Apache License, Version 2.0 (the
12		"License"); you may not use this file except in compliance
13		with the License. You may obtain a copy of the License at
14
15		http://www.apache.org/licenses/LICENSE-2.0
16
17		Unless required by applicable law or agreed to in writing, software
18		distributed under the License is distributed on an "AS IS" BASIS,
19		WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20		See the License for the specific language governing permissions and
21		limitations under the License.
22		*/
23
24		#pragma once
25
26		#include <cstdint>
27		#include <string>
28		#include <string_view>
29		#include <vector>
30
31		#include "config/config_result.h"
32
33		namespace config
34		{
35
36		/**
37		* Represents a single storage span entry in storage.yaml.
38		*/
39		struct StorageSpanEntry {
40		std::string name;
41		std::string path;
42		std::string hash_seed; ///< optional
43		int64_t size = 0; ///< optional for raw device
44		};
45
46		/**
47		* Represents a single volume entry in storage.yaml.
48		*/
49		struct StorageVolumeEntry {
50		struct Size {
51		int64_t absolute_value = 0;
52		bool in_percent = false;
53		int percent = 0;
54
55		bool
56		is_empty() const
57	0	{
58	0	return !in_percent && absolute_value == 0;
59	0	}
60		};
61
62		struct SpanRef {
63		std::string use;
64		Size size;
65		};
66
67		int id = 0;
68		std::string scheme = "http";
69		Size size;
70		bool ram_cache = true;
71		int64_t ram_cache_size = -1;
72		int64_t ram_cache_cutoff = -1;
73		int avg_obj_size = -1;
74		int fragment_size = -1;
75		std::vector<SpanRef> spans;
76		};
77
78		/**
79		* Top-level storage configuration.
80		*/
81		struct StorageConfig {
82		std::vector<StorageSpanEntry> spans;
83		std::vector<StorageVolumeEntry> volumes;
84		};
85
86		/**
87		* Parser for storage.yaml / storage.config configuration files.
88		*
89		* Supports both the current YAML format (storage.yaml) and the legacy
90		* line-based format (storage.config). The format is auto-detected by
91		* file extension when parse() is used: files ending in ".yaml" are
92		* parsed as YAML; all others are parsed as legacy storage.config.
93		*/
94		class StorageParser
95		{
96		public:
97		/**
98		* Parse a storage configuration file.
99		*
100		* Files ending in ".yaml" are parsed as YAML (storage.yaml); all other
101		* files are parsed using the legacy storage.config line-based format.
102		*
103		* @param[in] filename Path to the configuration file.
104		* @return ConfigResult containing the parsed configuration or errors.
105		*/
106		ConfigResult<StorageConfig> parse(std::string const &filename);
107
108		/**
109		* Parse storage.yaml content from a string (useful for unit tests).
110		*
111		* @param[in] content The YAML content to parse.
112		* @return ConfigResult containing the parsed configuration or errors.
113		*/
114		ConfigResult<StorageConfig> parse_content(std::string_view content);
115
116		/**
117		* Parse legacy storage.config content from a string.
118		*
119		* Each non-blank, non-comment line has the form:
120		* pathname [size_bytes] [id=hash_seed] [volume=N]
121		*
122		* Spans whose lines carry a "volume=N" annotation produce a
123		* StorageVolumeEntry with id=N and a span-ref to the span.
124		*
125		* @param[in] content The legacy storage.config content to parse.
126		* @return ConfigResult containing the parsed configuration or errors.
127		*/
128		ConfigResult<StorageConfig> parse_legacy_storage_content(std::string_view content);
129		};
130
131		/**
132		* Parser for the legacy volume.config configuration file.
133		*
134		* Each non-blank, non-comment line has the form:
135		* volume=N scheme=http size=V[%] [avg_obj_size=V] [fragment_size=V]
136		* [ramcache=true\|false]
137		* [ram_cache_size=V] [ram_cache_cutoff=V]
138		*
139		* Absolute sizes are in megabytes; percent sizes are written as "N%".
140		*/
141		class VolumeParser
142		{
143		public:
144		/**
145		* Parse a volume.config file.
146		*
147		* @param[in] filename Path to the configuration file.
148		* @return ConfigResult whose value has only the volumes field populated.
149		*/
150		ConfigResult<StorageConfig> parse(std::string const &filename);
151
152		/**
153		* Parse legacy volume.config content from a string (useful for unit tests).
154		*
155		* @param[in] content The legacy volume.config content to parse.
156		* @return ConfigResult whose value has only the volumes field populated.
157		*/
158		ConfigResult<StorageConfig> parse_content(std::string_view content);
159		};
160
161		/**
162		* Merge a legacy storage.config result with a legacy volume.config result.
163		*
164		* The spans come from @a storage (the storage.config parse result).
165		* If @a volumes contains any volume entries (the volume.config parse result),
166		* they replace the minimal volume entries produced by storage.config
167		* "volume=N" annotations, while preserving the span-ref associations that
168		* those annotations recorded. If @a volumes is empty, the partial volume
169		* entries from @a storage are kept as-is.
170		*
171		* @param[in] storage Result of StorageParser::parse_legacy_storage_content().
172		* @param[in] volumes Result of VolumeParser::parse_content() (may be empty).
173		* @return Merged StorageConfig ready for marshalling.
174		*/
175		StorageConfig merge_legacy_storage_configs(StorageConfig const &storage, StorageConfig const &volumes);
176
177		/**
178		* Marshaller for storage configuration.
179		*
180		* Serializes configuration to YAML or JSON format.
181		*/
182		class StorageMarshaller
183		{
184		public:
185		/**
186		* Serialize configuration to YAML format.
187		*
188		* @param[in] config The configuration to serialize.
189		* @return YAML string representation.
190		*/
191		std::string to_yaml(StorageConfig const &config);
192
193		/**
194		* Serialize configuration to JSON format.
195		*
196		* @param[in] config The configuration to serialize.
197		* @return JSON string representation.
198		*/
199		std::string to_json(StorageConfig const &config);
200		};
201
202		} // namespace config