importer

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package importer — реестр форматов наполнения (jsonc/json, yaml/yml, ndjson): упорядоченное дерево значений, семантика секций, Issues-модель и дословные тексты ошибок формата (docs/plan/01-architecture.md §2.5). Оркестратор Import работает поверх сервисного слоя (разбор файла → применение секции catalog → upsert записей), экспорт — round-trip во всех форматах реестра (записи и каталог).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ReadDocument

func ReadDocument(root value, snap *catalog.Snapshot) (doc *Document, issues []Issue)

ReadDocument разбирает корень документа (jsonc/yaml): секция catalog пропускается (импортёр применяет её до записей отдельно), секция sources — тоже (определения источников применяются до записей), записи классов читаются в порядке следования ключей. Проблемы формы накапливаются в issues; записи с проблемами не попадают в Document (применение частичной записи запрещено).

func ReadRecordJSON

func ReadRecordJSON(data []byte, snap *catalog.Snapshot) (service.DeviceInput, error)

ReadRecordJSON читает одну запись наполнения из тела REST-запроса (POST/PUT /api/v1/components — docs/plan/04-module-functionality.md §2): строка-обозначение либо объект «name/system + секции». Разбор — общим читателем формата (дубликаты ключей, форма секций, тексты проблем); класс записи определяется автодетектом по обозначению (для system other создание адресуется PUT с классом в пути). Возвращается первая проблема (REST применяет одну запись, Issues-накопление прогона здесь нет).

func ReadRecordLine

func ReadRecordLine(snap *catalog.Snapshot, v value, line int) (Record, bool, []Issue)

ReadRecordLine читает строку-обёртку NDJSON {"<класс>": <запись>} — одна JSON-строка, одна сущность: ровно один ключ-класс.

Types

type Document

type Document struct {
	Records  []Record
	Rejected int
}

Document — разобранный документ наполнения (jsonc/yaml): записи в порядке файла и число записей, отвергнутых при чтении (проблемы — в Issues; дерево секции catalog импортёр применяет до записей).

type Format

type Format string

Format — формат файла наполнения (реестр форматов — docs/plan/04-module-functionality.md §4): jsonc/json и yaml/yml — документы целиком, ndjson — построчный поток для больших объёмов.

const (
	FormatJSONC  Format = "jsonc"
	FormatYAML   Format = "yaml"
	FormatNDJSON Format = "ndjson"
)

Реестр форматов наполнения.

func FormatByFilename

func FormatByFilename(name string) (Format, error)

FormatByFilename определяет формат по расширению имени файла. Имя «-» (стандартный ввод) читается как jsonc — формат экспорта по умолчанию.

func ParseFormat

func ParseFormat(s string) (Format, error)

ParseFormat разбирает имя формата (опция --format, нижний регистр).

func (Format) Known

func (f Format) Known() bool

Known сообщает, входит ли формат в реестр.

type ImportOption added in v0.0.5

type ImportOption func(*importOptions)

ImportOption — опция прогона импорта (Import/ImportCatalogFile).

func WithProgress added in v0.0.5

func WithProgress(fn func(Progress)) ImportOption

WithProgress — колбэк прогресса прогона: снимки нарастающих счётчиков по ходу чтения и применения (см. Progress). Вызывается синхронно в горутине прогона: быстрый возврат, долгая обработка останавливает импорт (отмена — контекст прогона).

type Importer

type Importer struct {
	// contains filtered or unexported fields
}

Importer — импорт/экспорт файлов наполнения поверх сервисного слоя приложения (docs/plan/04-module-functionality.md §1.1 ImportService).

func New

func New(app *service.App) *Importer

New создаёт импортёра над приложением.

func (*Importer) Export

func (m *Importer) Export(ctx context.Context, w io.Writer, format Format, kind *domain.Kind) error

Export выгружает записи устройств (все классы либо один) в формате наполнения: jsonc/yaml — документ с секциями классов, ndjson — по строке-обёртке на запись.

func (*Importer) ExportCatalog

func (m *Importer) ExportCatalog(ctx context.Context, w io.Writer, format Format) error

ExportCatalog выгружает каталог (снимок определений) в формате наполнения: секция catalog со всеми подразделами.

func (*Importer) Import

func (m *Importer) Import(ctx context.Context, r io.Reader, name string, dryRun bool,
	opts ...ImportOption) (Report, error)

Import импортирует файл наполнения (формат — по расширению имени). Жёсткая ошибка (возвращается как error, прогона нет) — только синтаксис формата; проблемы формы и значений накапливаются в Report.Issues: корректные записи применяются, ошибочные — нет (запись не применяется вовсе, частичное применение записи запрещено). Опции: WithProgress — колбэк нарастающих счётчиков чтения и применения (NDJSON читается построчно, без загрузки файла целиком).

func (*Importer) ImportCatalogFile

func (m *Importer) ImportCatalogFile(ctx context.Context, r io.Reader, name string,
	dryRun bool, opts ...ImportOption) (Report, error)

ImportCatalogFile применяет только секцию catalog файла наполнения (catalog import): записи в файле не допускаются — для них есть import. Смешанный файл отвергается до каких-либо записей в БД: признак «есть записи» известен фазе чтения, применение каталога отложено до проверки.

func (*Importer) ImportFormat added in v0.2.1

func (m *Importer) ImportFormat(ctx context.Context, r io.Reader, format Format,
	dryRun bool, opts ...ImportOption) (Report, error)

ImportFormat импортирует файл наполнения заданного формата — имя файла не участвует (REST: формат согласован заголовком Content-Type; встраивание: формат выбран явно). Условное имя отчёта — «import.<формат>». Контракт исходов и проблем — как у Import.

type Issue

type Issue struct {
	Record  string // обозначение записи («» — проблема корневого уровня)
	Line    int    // номер строки NDJSON (0 — не определён)
	No      int    // порядковый номер записи в секции документа (0 — не задан)
	Code    domain.Code
	MsgID   domain.MsgID
	Args    []any
	Message string
}

Issue — проблема прогона импорта (Issues-модель — docs/plan/04-module-functionality.md §4): корневые проблемы и проблемы записей накапливаются за один прогон; жёсткой ошибкой (возвращаемой как error) остаётся только синтаксис формата. Сообщение — MsgID каталога + аргументы (этап 8.3); Message — канонический en-рендер, локализованный рендер и сборка позиции — слой вывода CLI. Тексты — контракт CLI.

func ReadCatalogSection

func ReadCatalogSection(v value) (catalog.Input, []Issue)

ReadCatalogSection читает дерево секции catalog в каталог. Значение null/отсутствие — пустой вход. Строки NDJSON ({"catalog": {"<подраздел>": […]}}) читаются тем же читателем и сливаются mergeCatalogTrees.

func ReadSourcesSection added in v0.3.0

func ReadSourcesSection(v value) ([]service.SourceInput, []Issue)

ReadSourcesSection читает корневую секцию sources — массив определений источников. Значение null/отсутствие — пустой вход; строки NDJSON ({"sources": […]}) читаются тем же читателем и сливаются конкатенацией массивов (importNDJSON).

func (Issue) String

func (i Issue) String() string

String — каноническая строка для вывода: позиция и текст.

type Progress added in v0.0.5

type Progress struct {
	Read    int // записей прочитано из файла (включая отвергнутых чтением)
	Applied int // записей доведено до исхода применения (Added/Updated/Skipped/Rejected)
	Line    int // номер последней прочитанной строки NDJSON (0 — не определён)
}

Progress — снимок прогресса прогона импорта: нарастающие счётчики чтения файла и применения записей. Колбэк WithProgress вызывается по ходу прогона: NDJSON — после каждой прочитанной записи (строки catalog записями не считаются), форматы-документы (jsonc/yaml) читаются целиком — чтение отмечается одним вызовом после разбора; применение записей (все форматы, включая dry-run) — по итоговому исходу каждой записи. Отвергнутые чтением записи входят в Read и не входят в Applied — применяются только прошедшие чтение.

type Record

type Record struct {
	Kind  domain.Kind
	Input service.DeviceInput
	Line  int // номер строки NDJSON (0 — не определён)
	No    int // порядковый номер записи в секции документа (0 — не задан)
}

Record — запись наполнения из файла: класс (по ключу секции корня либо строке-обёртке NDJSON) и вход сервисного слоя.

type Report

type Report struct {
	Name           string
	Format         Format
	DryRun         bool
	Records        int // записей в файле (включая отвергнутые)
	Added          int
	Updated        int
	Skipped        int
	Rejected       int // записи, не применённые из-за проблем
	CatalogApplied bool
	SourcesApplied bool // реестр источников изменён корневой секцией sources
	Issues         []Issue
}

Report — итог прогона импорта: счётчики исходов записей и накопленные проблемы (Issues-модель: полный список за один прогон).

func (*Report) HasIssues

func (r *Report) HasIssues() bool

HasIssues сообщает, были ли проблемы прогона.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL