001/*
002 * Logback: the reliable, generic, fast and flexible logging framework.
003 * Copyright (C) 1999-2026, QOS.ch. All rights reserved.
004 *
005 * This program and the accompanying materials are dual-licensed under
006 * either the terms of the Eclipse Public License v2.0 as published by
007 * the Eclipse Foundation
008 *
009 *   or (per the licensee's choosing)
010 *
011 * under the terms of the GNU Lesser General Public License version 2.1
012 * as published by the Free Software Foundation.
013 */
014package ch.qos.logback.core.kryo;
015
016import com.esotericsoftware.kryo.kryo5.Kryo;
017import com.esotericsoftware.kryo.kryo5.KryoException;
018import com.esotericsoftware.kryo.kryo5.Serializer;
019import com.esotericsoftware.kryo.kryo5.io.Input;
020import com.esotericsoftware.kryo.kryo5.io.Output;
021import com.esotericsoftware.kryo.kryo5.minlog.Log;
022
023import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC3_POLY;
024import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC_BITS;
025import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC_MASK;
026import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_DATA_BITS;
027import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_DATA_MASK;
028import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_ID_MASK;
029import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_NEW_FLAG;
030import static ch.qos.logback.core.kryo.KryoCoreConstants.MAX_SERIALIZER_ID;
031import static ch.qos.logback.core.kryo.KryoCoreConstants.UNREGISTERED_ID;
032
033/**
034 * Base Kryo serializer with optional value↔id caching.
035 *
036 * <p>When a bimap is configured, each value is introduced with a 2-byte header packing
037 * a 13-bit data word (NEW/CACHED flag + 12-bit id) and a 3-bit CRC over those data bits.
038 * Ids must be in {@code 1..MAX_SERIALIZER_ID}, or {@link KryoCoreConstants#UNREGISTERED_ID}
039 * for frequency-gated non-registrations. Cached hits write only that header; new values also
040 * write the payload via {@link #writeNewEntry}.
041 *
042 * @see KryoCoreConstants#ENTRY_HEADER_NEW_FLAG
043 */
044public abstract class SerializerBase<V> extends Serializer<V> {
045
046    public enum BiMapType {
047        NONE,
048        DIRECT_MAP,
049        FREQUENCY_GATED,
050        /** Cache hits use {@code ==}, not {@code equals}/{@code hashCode}. */
051        IDENTITY
052    }
053
054
055    final int capacity;
056    final BidirectionalObjectToIdMap<V> bimap;
057
058    public SerializerBase(int capacity) {
059
060        this(BiMapType.DIRECT_MAP, capacity);
061        if(capacity < 1024) {
062            System.out.println("WARNING: capacity less than 1024");
063        }
064    }
065
066    public SerializerBase(BiMapType biMapType, int capacity) {
067        this.capacity = capacity;
068
069        switch (biMapType) {
070            case NONE:
071                this.bimap = null;
072                break;
073            case DIRECT_MAP:
074                this.bimap = new BidirectionalObjectToIdMapDefault<>(capacity);
075                break;
076            case FREQUENCY_GATED:
077                this.bimap = new BidirectionalObjectToIdMapDefault(capacity); //FrequencyGatedBidirectionalObjectToIdMap<>(capacity);
078                break;
079            case IDENTITY:
080                this.bimap = new BidirectionalObjectToIdMapIdentity<>(capacity);
081                break;
082            default:
083                throw new IllegalArgumentException("Unsupported BiMapType: " + biMapType);
084        }
085        Log.debug(this.getClass().getSimpleName() + " bimap:"+biMapType+" capacity: " + capacity);
086    }
087
088
089    @Override
090    public void write(Kryo kryo, Output output, V value) {
091
092        // no bimap, just write the value directly
093        if (bimap == null) {
094            writeNewEntry(kryo, output, value);
095            return;
096        }
097
098        Integer existingId = this.bimap.getIdByValue(value);
099
100        if (existingId == null) {
101            final int newId = this.bimap.insertNewEntryOnWrite(value);
102            writeEntryHeader(output, true, newId);
103            //Log.debug("SerializerBase.write writing new value [" + value + "] with id: " + newId);
104            writeNewEntry(kryo, output, value);
105        } else {
106            //Log.debug("SerializerBase.write writing existing entry [" + value + "] with id: " + existingId);
107            writeEntryHeader(output, false, existingId);
108        }
109
110    }
111
112    /**
113     * Method called to write new entries.
114     *
115     * @param kryo
116     * @param output
117     * @param value
118     */
119    abstract protected void writeNewEntry(Kryo kryo, Output output, V value);
120
121    @Override
122    public V read(Kryo kryo, Input input, Class<? extends V> type) {
123
124        if (bimap == null) {
125            return readNewEntry(kryo, input);
126        }
127
128        int data13 = readEntryHeaderData(input);
129        boolean isNewEntry = (data13 & ENTRY_HEADER_NEW_FLAG) != 0;
130        int id = decodeHeaderId(data13);
131
132        if (isNewEntry) {
133            V deserialized = readNewEntry(kryo, input);
134            if (id != UNREGISTERED_ID) {
135                V existingVal = bimap.insertNewEntryOnRead(id, deserialized);
136                if (existingVal != null) {
137                    Log.warn("SerializerBase.read returned non-null existingVal for value id: " + id);
138                }
139            }
140            Log.debug("NEW entry for id: " + id + ", value: " + deserialized);
141            return deserialized;
142        } else {
143            V value = bimap.getValueById(id);
144            Log.debug("Cached entry for id: " + id + ", value: " + value);
145            return value;
146        }
147    }
148
149    abstract protected V readNewEntry(Kryo kryo, Input input);
150
151    /**
152     * Writes a 2-byte entry header: 13-bit data (NEW flag + id) and a 3-bit CRC over that data.
153     * {@link KryoCoreConstants#UNREGISTERED_ID} is stored as id 0 (valid only with NEW).
154     */
155    static void writeEntryHeader(Output output, boolean newEntry, int id) {
156        int idBits;
157        if (id == UNREGISTERED_ID) {
158            if (!newEntry) {
159                throw new IllegalArgumentException("UNREGISTERED_ID is only valid for NEW_ENTRY");
160            }
161            idBits = 0;
162        } else {
163            if (id < 1 || id > MAX_SERIALIZER_ID) {
164                throw new IllegalStateException(
165                        "Serializer id out of range: " + id + " (allowed 1.." + MAX_SERIALIZER_ID + ")");
166            }
167            idBits = id;
168        }
169        int data13 = (newEntry ? ENTRY_HEADER_NEW_FLAG : 0) | (idBits & ENTRY_HEADER_ID_MASK);
170        int crc = crc3(data13);
171        int packed = (data13 << ENTRY_HEADER_CRC_BITS) | crc;
172        output.writeShort(packed);
173    }
174
175    /**
176     * Reads a 2-byte entry header, verifies the CRC, and returns the 13-bit data word.
177     *
178     * @throws KryoException if the CRC does not match
179     */
180    static int readEntryHeaderData(Input input) {
181        int packed = input.readShort() & 0xFFFF;
182        int data13 = (packed >>> ENTRY_HEADER_CRC_BITS) & ENTRY_HEADER_DATA_MASK;
183        int crc = packed & ENTRY_HEADER_CRC_MASK;
184        int expected = crc3(data13);
185        if (crc != expected) {
186            throw new KryoException(
187                    "SerializerBase entry header CRC mismatch: got " + crc + ", expected " + expected
188                            + " (data=0x" + Integer.toHexString(data13) + ")");
189        }
190        return data13;
191    }
192
193    /**
194     * Decodes the id from a verified 13-bit data word.
195     * Id bits {@code 0} on a NEW entry mean {@link KryoCoreConstants#UNREGISTERED_ID}.
196     */
197    static int decodeHeaderId(int data13) {
198        int idBits = data13 & ENTRY_HEADER_ID_MASK;
199        boolean isNew = (data13 & ENTRY_HEADER_NEW_FLAG) != 0;
200        if (isNew && idBits == 0) {
201            return UNREGISTERED_ID;
202        }
203        return idBits;
204    }
205
206    /**
207     * CRC-3 over the low {@link KryoCoreConstants#ENTRY_HEADER_DATA_BITS} of {@code data},
208     * polynomial {@link KryoCoreConstants#ENTRY_HEADER_CRC3_POLY} ({@code x^3 + x + 1}).
209     *
210     * <p>MSB-first residual: remainder of {@code (data << 3)} modulo the generator.
211     */
212    static int crc3(int data) {
213        int v = (data & ENTRY_HEADER_DATA_MASK) << ENTRY_HEADER_CRC_BITS;
214        for (int i = ENTRY_HEADER_DATA_BITS + ENTRY_HEADER_CRC_BITS - 1; i >= ENTRY_HEADER_CRC_BITS; i--) {
215            if (((v >> i) & 1) != 0) {
216                v ^= ENTRY_HEADER_CRC3_POLY << (i - ENTRY_HEADER_CRC_BITS);
217            }
218        }
219        return v & ENTRY_HEADER_CRC_MASK;
220    }
221}